Ticket #7038: wpdb.phpdoc.r8094.diff

File wpdb.phpdoc.r8094.diff, 17.9 KB (added by jacobsantos, 5 years ago)

Complete the rest of the wpdb object inline documentation based off of r8094

  • wp-db.php

     
    11<?php 
    2 //  WordPress DB Class 
     2/** 
     3 * WordPress DB Class 
     4 * 
     5 * Original code from {@link http://php.justinvincent.com Justin Vincent (justin@visunet.ie)} 
     6 * 
     7 * @package WordPress 
     8 * @subpackage Database 
     9 * @since 0.71 
     10 */ 
    311 
    4 //  ORIGINAL CODE FROM: 
    5 //  Justin Vincent (justin@visunet.ie) 
    6 //      http://php.justinvincent.com 
     12/** 
     13 * @since 0.71 
     14 */ 
     15define('EZSQL_VERSION', 'WP1.25'); 
    716 
    8 define('EZSQL_VERSION', 'WP1.25'); 
     17/** 
     18 * @since 0.71 
     19 */ 
    920define('OBJECT', 'OBJECT', true); 
     21 
     22/** 
     23 * @since {@internal Version Unknown}} 
     24 */ 
    1025define('OBJECT_K', 'OBJECT_K', false); 
     26 
     27/** 
     28 * @since 0.71 
     29 */ 
    1130define('ARRAY_A', 'ARRAY_A', false); 
     31 
     32/** 
     33 * @since 0.71 
     34 */ 
    1235define('ARRAY_N', 'ARRAY_N', false); 
    1336 
     37/** 
     38 * Whether to save queries, defaults to false. 
     39 * @since 1.0.0 
     40 */ 
    1441if (!defined('SAVEQUERIES')) 
    1542        define('SAVEQUERIES', false); 
    1643 
     44/** 
     45 * WordPress Database Access Abstraction Object 
     46 * 
     47 * It is possible to replace this class with your own 
     48 * by setting the $wpdb global variable in wp-content/wpdb.php 
     49 * file with your class. You can name it wpdb also, since 
     50 * this file will not be included, if the other file is 
     51 * available. 
     52 * 
     53 * @link http://codex.wordpress.org/Function_Reference/wpdb_Class 
     54 * 
     55 * @package WordPress 
     56 * @subpackage Database 
     57 * @since 0.71 
     58 * @final 
     59 */ 
    1760class wpdb { 
    1861 
     62        /** 
     63         * Whether to show SQL/DB errors 
     64         * 
     65         * @since 0.71 
     66         * @access private 
     67         * @var bool 
     68         */ 
    1969        var $show_errors = false; 
     70 
     71        /** 
     72         * Whether to suppress errors during the DB bootstrapping. 
     73         * 
     74         * @access private 
     75         * @since {@internal Version Unknown}} 
     76         * @var bool 
     77         */ 
    2078        var $suppress_errors = false; 
     79 
     80        /** 
     81         * The last error during query. 
     82         * 
     83         * @since {@internal Version Unknown}} 
     84         * @var string 
     85         */ 
    2186        var $last_error = ''; 
     87 
     88        /** 
     89         * Amount of queries made 
     90         * 
     91         * @since 1.2.0 
     92         * @access private 
     93         * @var int 
     94         */ 
    2295        var $num_queries = 0; 
     96 
     97        /** 
     98         * Saved result of the last query made 
     99         * 
     100         * @since 1.2.0 
     101         * @access private 
     102         * @var array 
     103         */ 
    23104        var $last_query; 
     105 
     106        /** 
     107         * Saved info on the table column 
     108         * 
     109         * @since 1.2.0 
     110         * @access private 
     111         * @var array 
     112         */ 
    24113        var $col_info; 
     114 
     115        /** 
     116         * Saved queries that were executed 
     117         * 
     118         * @since 1.5.0 
     119         * @access private 
     120         * @var array 
     121         */ 
    25122        var $queries; 
     123 
     124        /** 
     125         * WordPress table prefix 
     126         * 
     127         * You can set this to have multiple WordPress installations 
     128         * in a single database. The second reason is for possible 
     129         * security precautions. 
     130         * 
     131         * @since 0.71 
     132         * @access private 
     133         * @var string 
     134         */ 
    26135        var $prefix = ''; 
     136 
     137        /** 
     138         * Whether the database queries are ready to start executing. 
     139         * 
     140         * @since 2.5.0 
     141         * @access private 
     142         * @var bool 
     143         */ 
    27144        var $ready = false; 
    28145 
    29         // Our tables 
     146        /** 
     147         * WordPress Posts table 
     148         * 
     149         * @since 1.5.0 
     150         * @access public 
     151         * @var string 
     152         */ 
    30153        var $posts; 
     154 
     155        /** 
     156         * WordPress Users table 
     157         * 
     158         * @since 1.5.0 
     159         * @access public 
     160         * @var string 
     161         */ 
    31162        var $users; 
     163 
     164        /** 
     165         * WordPress Categories table 
     166         * 
     167         * @since 1.5.0 
     168         * @access public 
     169         * @var string 
     170         */ 
    32171        var $categories; 
     172 
     173        /** 
     174         * WordPress Post to Category table 
     175         * 
     176         * @since 1.5.0 
     177         * @access public 
     178         * @var string 
     179         */ 
    33180        var $post2cat; 
     181 
     182        /** 
     183         * WordPress Comments table 
     184         * 
     185         * @since 1.5.0 
     186         * @access public 
     187         * @var string 
     188         */ 
    34189        var $comments; 
     190 
     191        /** 
     192         * WordPress Links table 
     193         * 
     194         * @since 1.5.0 
     195         * @access public 
     196         * @var string 
     197         */ 
    35198        var $links; 
     199 
     200        /** 
     201         * WordPress Options table 
     202         * 
     203         * @since 1.5.0 
     204         * @access public 
     205         * @var string 
     206         */ 
    36207        var $options; 
     208 
     209        /** 
     210         * WordPress Post Metadata table 
     211         * 
     212         * @since {@internal Version Unknown}} 
     213         * @access public 
     214         * @var string 
     215         */ 
    37216        var $postmeta; 
     217 
     218        /** 
     219         * WordPress User Metadata table 
     220         * 
     221         * @since 2.3.0 
     222         * @access public 
     223         * @var string 
     224         */ 
    38225        var $usermeta; 
     226 
     227        /** 
     228         * WordPress Terms table 
     229         * 
     230         * @since 2.3.0 
     231         * @access public 
     232         * @var string 
     233         */ 
    39234        var $terms; 
     235 
     236        /** 
     237         * WordPress Term Taxonomy table 
     238         * 
     239         * @since 2.3.0 
     240         * @access public 
     241         * @var string 
     242         */ 
    40243        var $term_taxonomy; 
     244 
     245        /** 
     246         * WordPress Term Relationships table 
     247         * 
     248         * @since 2.3.0 
     249         * @access public 
     250         * @var string 
     251         */ 
    41252        var $term_relationships; 
     253 
     254        /** 
     255         * List of WordPress tables 
     256         * 
     257         * @since {@internal Version Unknown}} 
     258         * @access private 
     259         * @var array 
     260         */ 
    42261        var $tables = array('users', 'usermeta', 'posts', 'categories', 'post2cat', 'comments', 'links', 'link2cat', 'options', 
    43262                        'postmeta', 'terms', 'term_taxonomy', 'term_relationships'); 
     263 
     264        /** 
     265         * Database table columns charset 
     266         * 
     267         * @since 2.2.0 
     268         * @access public 
     269         * @var string 
     270         */ 
    44271        var $charset; 
     272 
     273        /** 
     274         * Database table columns collate 
     275         * 
     276         * @since 2.2.0 
     277         * @access public 
     278         * @var string 
     279         */ 
    45280        var $collate; 
    46281 
    47282        /** 
    48283         * Connects to the database server and selects a database 
    49          * @param string $dbuser 
    50          * @param string $dbpassword 
    51          * @param string $dbname 
    52          * @param string $dbhost 
     284         * 
     285         * PHP4 compatibility layer for calling the PHP5 constructor. 
     286         * 
     287         * @uses wpdb::__construct() Passes parameters and returns result 
     288         * @since 0.71 
     289         * 
     290         * @param string $dbuser MySQL database user 
     291         * @param string $dbpassword MySQL database password 
     292         * @param string $dbname MySQL database name 
     293         * @param string $dbhost MySQL database host 
    53294         */ 
    54295        function wpdb($dbuser, $dbpassword, $dbname, $dbhost) { 
    55296                return $this->__construct($dbuser, $dbpassword, $dbname, $dbhost); 
    56297        } 
    57298 
     299        /** 
     300         * Connects to the database server and selects a database 
     301         * 
     302         * PHP5 style constructor for compatibility with PHP5. Does 
     303         * the actual setting up of the class properties and connection 
     304         * to the database. 
     305         * 
     306         * @since 2.0.8 
     307         * 
     308         * @param string $dbuser MySQL database user 
     309         * @param string $dbpassword MySQL database password 
     310         * @param string $dbname MySQL database name 
     311         * @param string $dbhost MySQL database host 
     312         */ 
    58313        function __construct($dbuser, $dbpassword, $dbname, $dbhost) { 
    59314                register_shutdown_function(array(&$this, "__destruct")); 
    60315 
    … …  
    100355                $this->select($dbname); 
    101356        } 
    102357 
     358        /** 
     359         * PHP5 style destructor and will run when database object is destroyed. 
     360         * 
     361         * @since 2.0.8 
     362         * 
     363         * @return bool Always true 
     364         */ 
    103365        function __destruct() { 
    104366                return true; 
    105367        } 
    106368 
     369        /** 
     370         * Sets the table prefix for the WordPress tables. 
     371         * 
     372         * Also allows for the CUSTOM_USER_TABLE and CUSTOM_USER_META_TABLE to 
     373         * override the WordPress users and usersmeta tables. 
     374         * 
     375         * @since 2.5.0 
     376         * 
     377         * @param string $prefix Alphanumeric name for the new prefix. 
     378         * @return string Old prefix 
     379         */ 
    107380        function set_prefix($prefix) { 
    108381 
    109382                if ( preg_match('|[^a-z0-9_]|i', $prefix) ) 
    … …  
    125398        } 
    126399 
    127400        /** 
    128          * Selects a database using the current class's $this->dbh 
    129          * @param string $db name 
     401         * Selects a database using the current database connection. 
     402         * 
     403         * The database name will be changed based on the current database 
     404         * connection. On failure, the execution will bail and display an DB error. 
     405         * 
     406         * @since 0.71 
     407         * 
     408         * @param string $db MySQL database name 
     409         * @return null Always null. 
    130410         */ 
    131411        function select($db) { 
    132412                if (!@mysql_select_db($db, $this->dbh)) { 
    … …  
    147427        /** 
    148428         * Escapes content for insertion into the database, for security 
    149429         * 
     430         * @since 0.71 
     431         * 
    150432         * @param string $string 
    151433         * @return string query safe string 
    152434         */ 
    … …  
    163445 
    164446        /** 
    165447         * Escapes content by reference for insertion into the database, for security 
     448         * 
     449         * @since 2.3.0 
     450         * 
    166451         * @param string $s 
    167452         */ 
    168453        function escape_by_ref(&$s) { 
    … …  
    170455        } 
    171456 
    172457        /** 
    173          * Prepares a SQL query for safe use, using sprintf() syntax 
     458         * Prepares a SQL query for safe use, using sprintf() syntax. 
     459         * 
     460         * @link http://php.net/sprintf See for syntax to use for query string. 
     461         * @since 2.3.0 
     462         * 
     463         * @param null|string $args If string, first parameter must be query statement 
     464         * @param mixed $args,... If additional parameters, they will be set inserted into the query. 
     465         * @return null|string Sanitized query string 
    174466         */ 
    175         function prepare($args=NULL) { 
    176                 if ( NULL === $args ) 
     467        function prepare($args=null) { 
     468                if ( is_null( $args ) ) 
    177469                        return; 
    178470                $args = func_get_args(); 
    179471                $query = array_shift($args); 
    … …  
    184476                return @vsprintf($query, $args); 
    185477        } 
    186478 
    187         // ================================================================== 
    188         //      Print SQL/DB error. 
    189  
     479        /** 
     480         * Print SQL/DB error. 
     481         * 
     482         * @since 0.71 
     483         * @global array $EZSQL_ERROR Stores error information of query and error string 
     484         * 
     485         * @param string $str The error to display 
     486         * @return bool False if the showing of errors is disabled. 
     487         */ 
    190488        function print_error($str = '') { 
    191489                global $EZSQL_ERROR; 
    192490 
    193491                if (!$str) $str = mysql_error($this->dbh); 
    194                 $EZSQL_ERROR[] = 
    195                 array ('query' => $this->last_query, 'error_str' => $str); 
     492                $EZSQL_ERROR[] = array ('query' => $this->last_query, 'error_str' => $str); 
    196493 
    197494                if ( $this->suppress_errors ) 
    198495                        return false; 
    … …  
    226523                </div>"; 
    227524        } 
    228525 
    229         // ================================================================== 
    230         //      Turn error handling on or off.. 
    231  
     526        /** 
     527         * Enables showing of database errors. 
     528         * 
     529         * This function should be used only to enable showing of errors. 
     530         * wpdb::hide_errors() should be used instead for hiding of errors. However, 
     531         * this function can be used to enable and disable showing of database 
     532         * errors. 
     533         * 
     534         * @since 0.71 
     535         * 
     536         * @param bool $show Whether to show or hide errors 
     537         * @return bool Old value for showing errors. 
     538         */ 
    232539        function show_errors( $show = true ) { 
    233540                $errors = $this->show_errors; 
    234541                $this->show_errors = $show; 
    235542                return $errors; 
    236543        } 
    237544 
     545        /** 
     546         * Disables showing of database errors. 
     547         * 
     548         * @since 0.71 
     549         * 
     550         * @return bool Whether showing of errors was active or not 
     551         */ 
    238552        function hide_errors() { 
    239553                $show = $this->show_errors; 
    240554                $this->show_errors = false; 
    241555                return $show; 
    242556        } 
    243557 
     558        /** 
     559         * Whether to suppress database errors. 
     560         * 
     561         * @param unknown_type $suppress 
     562         * @return unknown 
     563         */ 
    244564        function suppress_errors( $suppress = true ) { 
    245565                $errors = $this->suppress_errors; 
    246566                $this->suppress_errors = $suppress; 
    247567                return $errors; 
    248568        } 
    249569 
    250         // ================================================================== 
    251         //      Kill cached query results 
    252  
     570        /** 
     571         * Kill cached query results. 
     572         * 
     573         * @since 0.71 
     574         */ 
    253575        function flush() { 
    254576                $this->last_result = array(); 
    255577                $this->col_info = null; 
    256578                $this->last_query = null; 
    257579        } 
    258580 
    259         // ================================================================== 
    260         //      Basic Query     - see docs for more detail 
    261  
     581        /** 
     582         * Perform a MySQL database query, using current database connection. 
     583         * 
     584         * More information can be found on the codex page. 
     585         * 
     586         * @since 0.71 
     587         * 
     588         * @param string $query 
     589         * @return unknown 
     590         */ 
    262591        function query($query) { 
    263592                if ( ! $this->ready ) 
    264593                        return false; 
    … …  
    327656        } 
    328657 
    329658        /** 
    330          * Insert an array of data into a table 
     659         * Insert an array of data into a table. 
     660         * 
     661         * @since 2.5.0 
     662         * 
    331663         * @param string $table WARNING: not sanitized! 
    332          * @param array $data should not already be SQL-escaped 
    333          * @return mixed results of $this->query() 
     664         * @param array $data Should not already be SQL-escaped 
     665         * @return mixed Results of $this->query() 
    334666         */ 
    335667        function insert($table, $data) { 
    336668                $data = add_magic_quotes($data); 
    … …  
    339671        } 
    340672 
    341673        /** 
    342          * Update a row in the table with an array of data 
     674         * Update a row in the table with an array of data. 
     675         * 
     676         * @since 2.5.0 
     677         * 
    343678         * @param string $table WARNING: not sanitized! 
    344          * @param array $data should not already be SQL-escaped 
    345          * @param array $where a named array of WHERE column => value relationships.  Multiple member pairs will be joined with ANDs.  WARNING: the column names are not currently sanitized! 
    346          * @return mixed results of $this->query() 
     679         * @param array $data Should not already be SQL-escaped 
     680         * @param array $where A named array of WHERE column => value relationships.  Multiple member pairs will be joined with ANDs.  WARNING: the column names are not currently sanitized! 
     681         * @return mixed Results of $this->query() 
    347682         */ 
    348683        function update($table, $data, $where){ 
    349684                $data = add_magic_quotes($data); 
    … …  
    360695        } 
    361696 
    362697        /** 
    363          * Get one variable from the database 
    364          * @param string $query (can be null as well, for caching, see codex) 
    365          * @param int $x = 0 row num to return 
    366          * @param int $y = 0 col num to return 
    367          * @return mixed results 
     698         * Retrieve one variable from the database. 
     699         * 
     700         * This combines the functionality of wpdb::get_row() and wpdb::get_col(), 
     701         * so both the column and row can be picked. 
     702         * 
     703         * It is possible to use this function without executing more queries. If 
     704         * you already made a query, you can set the $query to 'null' value and just 
     705         * retrieve either the column and row of the last query result. 
     706         * 
     707         * @since 0.71 
     708         * 
     709         * @param string $query Can be null as well, for caching 
     710         * @param int $x Column num to return 
     711         * @param int $y Row num to return 
     712         * @return mixed Database query results 
    368713         */ 
    369714        function get_var($query=null, $x = 0, $y = 0) { 
    370715                $this->func_call = "\$db->get_var(\"$query\",$x,$y)"; 
    … …  
    381726        } 
    382727 
    383728        /** 
    384          * Get one row from the database 
    385          * @param string $query 
     729         * Retrieve one row from the database. 
     730         * 
     731         * @since 0.71 
     732         * 
     733         * @param string $query SQL query 
    386734         * @param string $output ARRAY_A | ARRAY_N | OBJECT 
    387          * @param int $y row num to return 
    388          * @return mixed results 
     735         * @param int $y Row num to return 
     736         * @return mixed Database query results 
    389737         */ 
    390738        function get_row($query = null, $output = OBJECT, $y = 0) { 
    391739                $this->func_call = "\$db->get_row(\"$query\",$output,$y)"; 
    … …  
    409757        } 
    410758 
    411759        /** 
    412          * Gets one column from the database 
    413          * @param string $query (can be null as well, for caching, see codex) 
    414          * @param int $x col num to return 
    415          * @return array results 
     760         * Retrieve one column from the database. 
     761         * 
     762         * @since 0.71 
     763         * 
     764         * @param string $query Can be null as well, for caching 
     765         * @param int $x Col num to return. Starts from 0. 
     766         * @return array Column results 
    416767         */ 
    417768        function get_col($query = null , $x = 0) { 
    418769                if ( $query ) 
    … …  
    427778        } 
    428779 
    429780        /** 
    430          * Return an entire result set from the database 
    431          * @param string $query (can also be null to pull from the cache) 
     781         * Retrieve an entire result set from the database. 
     782         * 
     783         * @since 0.71 
     784         * 
     785         * @param string|null $query Can also be null to pull from the cache 
    432786         * @param string $output ARRAY_A | ARRAY_N | OBJECT_K | OBJECT 
    433          * @return mixed results 
     787         * @return mixed Database query results 
    434788         */ 
    435789        function get_results($query = null, $output = OBJECT) { 
    436790                $this->func_call = "\$db->get_results(\"$query\", $output)"; 
    … …  
    472826        } 
    473827 
    474828        /** 
    475          * Grabs column metadata from the last query 
     829         * Retrieve column metadata from the last query. 
     830         * 
     831         * @since 0.71 
     832         * 
    476833         * @param string $info_type one of name, table, def, max_length, not_null, primary_key, multiple_key, unique_key, numeric, blob, type, unsigned, zerofill 
    477834         * @param int $col_offset 0: col name. 1: which table the col's in. 2: col's max length. 3: if the col is numeric. 4: col's type 
    478          * @return mixed results 
     835         * @return mixed Column Results 
    479836         */ 
    480837        function get_col_info($info_type = 'name', $col_offset = -1) { 
    481838                if ( $this->col_info ) { 
    … …  
    493850        } 
    494851 
    495852        /** 
    496          * Starts the timer, for debugging purposes 
     853         * Starts the timer, for debugging purposes. 
     854         * 
     855         * @since 1.5.0 
     856         * 
     857         * @return bool Always returns true 
    497858         */ 
    498859        function timer_start() { 
    499860                $mtime = microtime(); 
    … …  
    503864        } 
    504865 
    505866        /** 
    506          * Stops the debugging timer 
    507          * @return int total time spent on the query, in milliseconds 
     867         * Stops the debugging timer. 
     868         * 
     869         * @since 1.5.0 
     870         * 
     871         * @return int Total time spent on the query, in milliseconds 
    508872         */ 
    509873        function timer_stop() { 
    510874                $mtime = microtime(); 
    … …  
    516880 
    517881        /** 
    518882         * Wraps fatal errors in a nice header and footer and dies. 
     883         * 
     884         * @since 1.5.0 
     885         * 
    519886         * @param string $message 
     887         * @return unknown 
    520888         */ 
    521         function bail($message) { // Just wraps errors in a nice header and footer 
     889        function bail($message) { 
    522890                if ( !$this->show_errors ) { 
    523891                        if ( class_exists('WP_Error') ) 
    524892                                $this->error = new WP_Error('500', $message); 
    … …  
    530898        } 
    531899 
    532900        /** 
    533          * Checks wether of not the database version is high enough to support the features WordPress uses 
    534          * @global $wp_version 
     901         * Whether or not MySQL database is minimal required version. 
     902         * 
     903         * @since 2.5.0 
     904         * @uses $wp_version 
     905         * 
     906         * @return WP_Error 
    535907         */ 
    536908        function check_database_version() 
    537909        { 
    … …  
    543915        } 
    544916 
    545917        /** 
    546          * This function is called when WordPress is generating the table schema to determine wether or not the current database 
    547          * supports or needs the collation statements. 
     918         * Whether of not the database version supports collation. 
     919         * 
     920         * Called when WordPress is generating the table scheme. 
     921         * 
     922         * @since 2.5.0 
     923         * 
     924         * @return bool True if collation is supported, false if version does not 
    548925         */ 
    549926        function supports_collation() 
    550927        { 
    … …  
    552929        } 
    553930 
    554931        /** 
    555          * Get the name of the function that called wpdb. 
    556          * @return string the name of the calling function 
     932         * Retrieve the name of the function that called wpdb. 
     933         * 
     934         * Requires PHP 4.3 and searches up the list of functions until it reaches 
     935         * the one that would most logically had called this method. 
     936         * 
     937         * @since 2.5.0 
     938         * 
     939         * @return string The name of the calling function 
    557940         */ 
    558941        function get_caller() { 
    559942                // requires PHP 4.3+ 
    … …  
    581964 
    582965} 
    583966 
    584 if ( ! isset($wpdb) ) 
     967if ( ! isset($wpdb) ) { 
     968        /** 
     969         * WordPress Database Object, if it isn't set already in wp-content/wpdb.php 
     970         * @global object $wpdb Creates a new wpdb object based on wp-config.php Constants for the database 
     971         * @since 0.71 
     972         */ 
    585973        $wpdb = new wpdb(DB_USER, DB_PASSWORD, DB_NAME, DB_HOST); 
     974} 
    586975?>