WordPress.org

Make WordPress Core

Ticket #7038: wpdb.phpdoc.r8159.diff

File wpdb.phpdoc.r8159.diff, 17.7 KB (added by jacobsantos, 6 years ago)

Updated Wp-db.php for r8159

  • 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 * WordPress Database Access Abstraction Object 
     39 * 
     40 * It is possible to replace this class with your own 
     41 * by setting the $wpdb global variable in wp-content/wpdb.php 
     42 * file with your class. You can name it wpdb also, since 
     43 * this file will not be included, if the other file is 
     44 * available. 
     45 * 
     46 * @link http://codex.wordpress.org/Function_Reference/wpdb_Class 
     47 * 
     48 * @package WordPress 
     49 * @subpackage Database 
     50 * @since 0.71 
     51 * @final 
     52 */ 
    1453class wpdb { 
    1554 
     55        /** 
     56         * Whether to show SQL/DB errors 
     57         * 
     58         * @since 0.71 
     59         * @access private 
     60         * @var bool 
     61         */ 
    1662        var $show_errors = false; 
     63 
     64        /** 
     65         * Whether to suppress errors during the DB bootstrapping. 
     66         * 
     67         * @access private 
     68         * @since {@internal Version Unknown}} 
     69         * @var bool 
     70         */ 
    1771        var $suppress_errors = false; 
     72 
     73        /** 
     74         * The last error during query. 
     75         * 
     76         * @since {@internal Version Unknown}} 
     77         * @var string 
     78         */ 
    1879        var $last_error = ''; 
     80 
     81        /** 
     82         * Amount of queries made 
     83         * 
     84         * @since 1.2.0 
     85         * @access private 
     86         * @var int 
     87         */ 
    1988        var $num_queries = 0; 
     89 
     90        /** 
     91         * Saved result of the last query made 
     92         * 
     93         * @since 1.2.0 
     94         * @access private 
     95         * @var array 
     96         */ 
    2097        var $last_query; 
     98 
     99        /** 
     100         * Saved info on the table column 
     101         * 
     102         * @since 1.2.0 
     103         * @access private 
     104         * @var array 
     105         */ 
    21106        var $col_info; 
     107 
     108        /** 
     109         * Saved queries that were executed 
     110         * 
     111         * @since 1.5.0 
     112         * @access private 
     113         * @var array 
     114         */ 
    22115        var $queries; 
     116 
     117        /** 
     118         * WordPress table prefix 
     119         * 
     120         * You can set this to have multiple WordPress installations 
     121         * in a single database. The second reason is for possible 
     122         * security precautions. 
     123         * 
     124         * @since 0.71 
     125         * @access private 
     126         * @var string 
     127         */ 
    23128        var $prefix = ''; 
     129 
     130        /** 
     131         * Whether the database queries are ready to start executing. 
     132         * 
     133         * @since 2.5.0 
     134         * @access private 
     135         * @var bool 
     136         */ 
    24137        var $ready = false; 
    25138 
    26         // Our tables 
     139        /** 
     140         * WordPress Posts table 
     141         * 
     142         * @since 1.5.0 
     143         * @access public 
     144         * @var string 
     145         */ 
    27146        var $posts; 
     147 
     148        /** 
     149         * WordPress Users table 
     150         * 
     151         * @since 1.5.0 
     152         * @access public 
     153         * @var string 
     154         */ 
    28155        var $users; 
     156 
     157        /** 
     158         * WordPress Categories table 
     159         * 
     160         * @since 1.5.0 
     161         * @access public 
     162         * @var string 
     163         */ 
    29164        var $categories; 
     165 
     166        /** 
     167         * WordPress Post to Category table 
     168         * 
     169         * @since 1.5.0 
     170         * @access public 
     171         * @var string 
     172         */ 
    30173        var $post2cat; 
     174 
     175        /** 
     176         * WordPress Comments table 
     177         * 
     178         * @since 1.5.0 
     179         * @access public 
     180         * @var string 
     181         */ 
    31182        var $comments; 
     183 
     184        /** 
     185         * WordPress Links table 
     186         * 
     187         * @since 1.5.0 
     188         * @access public 
     189         * @var string 
     190         */ 
    32191        var $links; 
     192 
     193        /** 
     194         * WordPress Options table 
     195         * 
     196         * @since 1.5.0 
     197         * @access public 
     198         * @var string 
     199         */ 
    33200        var $options; 
     201 
     202        /** 
     203         * WordPress Post Metadata table 
     204         * 
     205         * @since {@internal Version Unknown}} 
     206         * @access public 
     207         * @var string 
     208         */ 
    34209        var $postmeta; 
     210 
     211        /** 
     212         * WordPress User Metadata table 
     213         * 
     214         * @since 2.3.0 
     215         * @access public 
     216         * @var string 
     217         */ 
    35218        var $usermeta; 
     219 
     220        /** 
     221         * WordPress Terms table 
     222         * 
     223         * @since 2.3.0 
     224         * @access public 
     225         * @var string 
     226         */ 
    36227        var $terms; 
     228 
     229        /** 
     230         * WordPress Term Taxonomy table 
     231         * 
     232         * @since 2.3.0 
     233         * @access public 
     234         * @var string 
     235         */ 
    37236        var $term_taxonomy; 
     237 
     238        /** 
     239         * WordPress Term Relationships table 
     240         * 
     241         * @since 2.3.0 
     242         * @access public 
     243         * @var string 
     244         */ 
    38245        var $term_relationships; 
     246 
     247        /** 
     248         * List of WordPress tables 
     249         * 
     250         * @since {@internal Version Unknown}} 
     251         * @access private 
     252         * @var array 
     253         */ 
    39254        var $tables = array('users', 'usermeta', 'posts', 'categories', 'post2cat', 'comments', 'links', 'link2cat', 'options', 
    40255                        'postmeta', 'terms', 'term_taxonomy', 'term_relationships'); 
     256 
     257        /** 
     258         * Database table columns charset 
     259         * 
     260         * @since 2.2.0 
     261         * @access public 
     262         * @var string 
     263         */ 
    41264        var $charset; 
     265 
     266        /** 
     267         * Database table columns collate 
     268         * 
     269         * @since 2.2.0 
     270         * @access public 
     271         * @var string 
     272         */ 
    42273        var $collate; 
    43274 
    44275        /** 
    45276         * Connects to the database server and selects a database 
    46          * @param string $dbuser 
    47          * @param string $dbpassword 
    48          * @param string $dbname 
    49          * @param string $dbhost 
     277         * 
     278         * PHP4 compatibility layer for calling the PHP5 constructor. 
     279         * 
     280         * @uses wpdb::__construct() Passes parameters and returns result 
     281         * @since 0.71 
     282         * 
     283         * @param string $dbuser MySQL database user 
     284         * @param string $dbpassword MySQL database password 
     285         * @param string $dbname MySQL database name 
     286         * @param string $dbhost MySQL database host 
    50287         */ 
    51288        function wpdb($dbuser, $dbpassword, $dbname, $dbhost) { 
    52289                return $this->__construct($dbuser, $dbpassword, $dbname, $dbhost); 
    53290        } 
    54291 
     292        /** 
     293         * Connects to the database server and selects a database 
     294         * 
     295         * PHP5 style constructor for compatibility with PHP5. Does 
     296         * the actual setting up of the class properties and connection 
     297         * to the database. 
     298         * 
     299         * @since 2.0.8 
     300         * 
     301         * @param string $dbuser MySQL database user 
     302         * @param string $dbpassword MySQL database password 
     303         * @param string $dbname MySQL database name 
     304         * @param string $dbhost MySQL database host 
     305         */ 
    55306        function __construct($dbuser, $dbpassword, $dbname, $dbhost) { 
    56307                register_shutdown_function(array(&$this, "__destruct")); 
    57308 
     
    97348                $this->select($dbname); 
    98349        } 
    99350 
     351        /** 
     352         * PHP5 style destructor and will run when database object is destroyed. 
     353         * 
     354         * @since 2.0.8 
     355         * 
     356         * @return bool Always true 
     357         */ 
    100358        function __destruct() { 
    101359                return true; 
    102360        } 
    103361 
     362        /** 
     363         * Sets the table prefix for the WordPress tables. 
     364         * 
     365         * Also allows for the CUSTOM_USER_TABLE and CUSTOM_USER_META_TABLE to 
     366         * override the WordPress users and usersmeta tables. 
     367         * 
     368         * @since 2.5.0 
     369         * 
     370         * @param string $prefix Alphanumeric name for the new prefix. 
     371         * @return string Old prefix 
     372         */ 
    104373        function set_prefix($prefix) { 
    105374 
    106375                if ( preg_match('|[^a-z0-9_]|i', $prefix) ) 
     
    122391        } 
    123392 
    124393        /** 
    125          * Selects a database using the current class's $this->dbh 
    126          * @param string $db name 
     394         * Selects a database using the current database connection. 
     395         * 
     396         * The database name will be changed based on the current database 
     397         * connection. On failure, the execution will bail and display an DB error. 
     398         * 
     399         * @since 0.71 
     400         * 
     401         * @param string $db MySQL database name 
     402         * @return null Always null. 
    127403         */ 
    128404        function select($db) { 
    129405                if (!@mysql_select_db($db, $this->dbh)) { 
     
    144420        /** 
    145421         * Escapes content for insertion into the database, for security 
    146422         * 
     423         * @since 0.71 
     424         * 
    147425         * @param string $string 
    148426         * @return string query safe string 
    149427         */ 
     
    160438 
    161439        /** 
    162440         * Escapes content by reference for insertion into the database, for security 
     441         * 
     442         * @since 2.3.0 
     443         * 
    163444         * @param string $s 
    164445         */ 
    165446        function escape_by_ref(&$s) { 
     
    167448        } 
    168449 
    169450        /** 
    170          * Prepares a SQL query for safe use, using sprintf() syntax 
     451         * Prepares a SQL query for safe use, using sprintf() syntax. 
     452         * 
     453         * @link http://php.net/sprintf See for syntax to use for query string. 
     454         * @since 2.3.0 
     455         * 
     456         * @param null|string $args If string, first parameter must be query statement 
     457         * @param mixed $args,... If additional parameters, they will be set inserted into the query. 
     458         * @return null|string Sanitized query string 
    171459         */ 
    172         function prepare($args=NULL) { 
    173                 if ( NULL === $args ) 
     460        function prepare($args=null) { 
     461                if ( is_null( $args ) ) 
    174462                        return; 
    175463                $args = func_get_args(); 
    176464                $query = array_shift($args); 
     
    181469                return @vsprintf($query, $args); 
    182470        } 
    183471 
    184         // ================================================================== 
    185         //      Print SQL/DB error. 
    186  
     472        /** 
     473         * Print SQL/DB error. 
     474         * 
     475         * @since 0.71 
     476         * @global array $EZSQL_ERROR Stores error information of query and error string 
     477         * 
     478         * @param string $str The error to display 
     479         * @return bool False if the showing of errors is disabled. 
     480         */ 
    187481        function print_error($str = '') { 
    188482                global $EZSQL_ERROR; 
    189483 
    190484                if (!$str) $str = mysql_error($this->dbh); 
    191                 $EZSQL_ERROR[] = 
    192                 array ('query' => $this->last_query, 'error_str' => $str); 
     485                $EZSQL_ERROR[] = array ('query' => $this->last_query, 'error_str' => $str); 
    193486 
    194487                if ( $this->suppress_errors ) 
    195488                        return false; 
     
    223516                </div>"; 
    224517        } 
    225518 
    226         // ================================================================== 
    227         //      Turn error handling on or off.. 
    228  
     519        /** 
     520         * Enables showing of database errors. 
     521         * 
     522         * This function should be used only to enable showing of errors. 
     523         * wpdb::hide_errors() should be used instead for hiding of errors. However, 
     524         * this function can be used to enable and disable showing of database 
     525         * errors. 
     526         * 
     527         * @since 0.71 
     528         * 
     529         * @param bool $show Whether to show or hide errors 
     530         * @return bool Old value for showing errors. 
     531         */ 
    229532        function show_errors( $show = true ) { 
    230533                $errors = $this->show_errors; 
    231534                $this->show_errors = $show; 
    232535                return $errors; 
    233536        } 
    234537 
     538        /** 
     539         * Disables showing of database errors. 
     540         * 
     541         * @since 0.71 
     542         * 
     543         * @return bool Whether showing of errors was active or not 
     544         */ 
    235545        function hide_errors() { 
    236546                $show = $this->show_errors; 
    237547                $this->show_errors = false; 
    238548                return $show; 
    239549        } 
    240550 
     551        /** 
     552         * Whether to suppress database errors. 
     553         * 
     554         * @param unknown_type $suppress 
     555         * @return unknown 
     556         */ 
    241557        function suppress_errors( $suppress = true ) { 
    242558                $errors = $this->suppress_errors; 
    243559                $this->suppress_errors = $suppress; 
    244560                return $errors; 
    245561        } 
    246562 
    247         // ================================================================== 
    248         //      Kill cached query results 
    249  
     563        /** 
     564         * Kill cached query results. 
     565         * 
     566         * @since 0.71 
     567         */ 
    250568        function flush() { 
    251569                $this->last_result = array(); 
    252570                $this->col_info = null; 
    253571                $this->last_query = null; 
    254572        } 
    255573 
    256         // ================================================================== 
    257         //      Basic Query     - see docs for more detail 
    258  
     574        /** 
     575         * Perform a MySQL database query, using current database connection. 
     576         * 
     577         * More information can be found on the codex page. 
     578         * 
     579         * @since 0.71 
     580         * 
     581         * @param string $query 
     582         * @return unknown 
     583         */ 
    259584        function query($query) { 
    260585                if ( ! $this->ready ) 
    261586                        return false; 
     
    324649        } 
    325650 
    326651        /** 
    327          * Insert an array of data into a table 
     652         * Insert an array of data into a table. 
     653         * 
     654         * @since 2.5.0 
     655         * 
    328656         * @param string $table WARNING: not sanitized! 
    329          * @param array $data should not already be SQL-escaped 
    330          * @return mixed results of $this->query() 
     657         * @param array $data Should not already be SQL-escaped 
     658         * @return mixed Results of $this->query() 
    331659         */ 
    332660        function insert($table, $data) { 
    333661                $data = add_magic_quotes($data); 
     
    336664        } 
    337665 
    338666        /** 
    339          * Update a row in the table with an array of data 
     667         * Update a row in the table with an array of data. 
     668         * 
     669         * @since 2.5.0 
     670         * 
    340671         * @param string $table WARNING: not sanitized! 
    341          * @param array $data should not already be SQL-escaped 
    342          * @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! 
    343          * @return mixed results of $this->query() 
     672         * @param array $data Should not already be SQL-escaped 
     673         * @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! 
     674         * @return mixed Results of $this->query() 
    344675         */ 
    345676        function update($table, $data, $where){ 
    346677                $data = add_magic_quotes($data); 
     
    357688        } 
    358689 
    359690        /** 
    360          * Get one variable from the database 
    361          * @param string $query (can be null as well, for caching, see codex) 
    362          * @param int $x = 0 row num to return 
    363          * @param int $y = 0 col num to return 
    364          * @return mixed results 
     691         * Retrieve one variable from the database. 
     692         * 
     693         * This combines the functionality of wpdb::get_row() and wpdb::get_col(), 
     694         * so both the column and row can be picked. 
     695         * 
     696         * It is possible to use this function without executing more queries. If 
     697         * you already made a query, you can set the $query to 'null' value and just 
     698         * retrieve either the column and row of the last query result. 
     699         * 
     700         * @since 0.71 
     701         * 
     702         * @param string $query Can be null as well, for caching 
     703         * @param int $x Column num to return 
     704         * @param int $y Row num to return 
     705         * @return mixed Database query results 
    365706         */ 
    366707        function get_var($query=null, $x = 0, $y = 0) { 
    367708                $this->func_call = "\$db->get_var(\"$query\",$x,$y)"; 
     
    378719        } 
    379720 
    380721        /** 
    381          * Get one row from the database 
    382          * @param string $query 
     722         * Retrieve one row from the database. 
     723         * 
     724         * @since 0.71 
     725         * 
     726         * @param string $query SQL query 
    383727         * @param string $output ARRAY_A | ARRAY_N | OBJECT 
    384          * @param int $y row num to return 
    385          * @return mixed results 
     728         * @param int $y Row num to return 
     729         * @return mixed Database query results 
    386730         */ 
    387731        function get_row($query = null, $output = OBJECT, $y = 0) { 
    388732                $this->func_call = "\$db->get_row(\"$query\",$output,$y)"; 
     
    406750        } 
    407751 
    408752        /** 
    409          * Gets one column from the database 
    410          * @param string $query (can be null as well, for caching, see codex) 
    411          * @param int $x col num to return 
    412          * @return array results 
     753         * Retrieve one column from the database. 
     754         * 
     755         * @since 0.71 
     756         * 
     757         * @param string $query Can be null as well, for caching 
     758         * @param int $x Col num to return. Starts from 0. 
     759         * @return array Column results 
    413760         */ 
    414761        function get_col($query = null , $x = 0) { 
    415762                if ( $query ) 
     
    424771        } 
    425772 
    426773        /** 
    427          * Return an entire result set from the database 
    428          * @param string $query (can also be null to pull from the cache) 
     774         * Retrieve an entire result set from the database. 
     775         * 
     776         * @since 0.71 
     777         * 
     778         * @param string|null $query Can also be null to pull from the cache 
    429779         * @param string $output ARRAY_A | ARRAY_N | OBJECT_K | OBJECT 
    430          * @return mixed results 
     780         * @return mixed Database query results 
    431781         */ 
    432782        function get_results($query = null, $output = OBJECT) { 
    433783                $this->func_call = "\$db->get_results(\"$query\", $output)"; 
     
    469819        } 
    470820 
    471821        /** 
    472          * Grabs column metadata from the last query 
     822         * Retrieve column metadata from the last query. 
     823         * 
     824         * @since 0.71 
     825         * 
    473826         * @param string $info_type one of name, table, def, max_length, not_null, primary_key, multiple_key, unique_key, numeric, blob, type, unsigned, zerofill 
    474827         * @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 
    475          * @return mixed results 
     828         * @return mixed Column Results 
    476829         */ 
    477830        function get_col_info($info_type = 'name', $col_offset = -1) { 
    478831                if ( $this->col_info ) { 
     
    490843        } 
    491844 
    492845        /** 
    493          * Starts the timer, for debugging purposes 
     846         * Starts the timer, for debugging purposes. 
     847         * 
     848         * @since 1.5.0 
     849         * 
     850         * @return bool Always returns true 
    494851         */ 
    495852        function timer_start() { 
    496853                $mtime = microtime(); 
     
    500857        } 
    501858 
    502859        /** 
    503          * Stops the debugging timer 
    504          * @return int total time spent on the query, in milliseconds 
     860         * Stops the debugging timer. 
     861         * 
     862         * @since 1.5.0 
     863         * 
     864         * @return int Total time spent on the query, in milliseconds 
    505865         */ 
    506866        function timer_stop() { 
    507867                $mtime = microtime(); 
     
    513873 
    514874        /** 
    515875         * Wraps fatal errors in a nice header and footer and dies. 
     876         * 
     877         * @since 1.5.0 
     878         * 
    516879         * @param string $message 
     880         * @return unknown 
    517881         */ 
    518         function bail($message) { // Just wraps errors in a nice header and footer 
     882        function bail($message) { 
    519883                if ( !$this->show_errors ) { 
    520884                        if ( class_exists('WP_Error') ) 
    521885                                $this->error = new WP_Error('500', $message); 
     
    527891        } 
    528892 
    529893        /** 
    530          * Checks wether of not the database version is high enough to support the features WordPress uses 
    531          * @global $wp_version 
     894         * Whether or not MySQL database is minimal required version. 
     895         * 
     896         * @since 2.5.0 
     897         * @uses $wp_version 
     898         * 
     899         * @return WP_Error 
    532900         */ 
    533901        function check_database_version() 
    534902        { 
     
    540908        } 
    541909 
    542910        /** 
    543          * This function is called when WordPress is generating the table schema to determine wether or not the current database 
    544          * supports or needs the collation statements. 
     911         * Whether of not the database version supports collation. 
     912         * 
     913         * Called when WordPress is generating the table scheme. 
     914         * 
     915         * @since 2.5.0 
     916         * 
     917         * @return bool True if collation is supported, false if version does not 
    545918         */ 
    546919        function supports_collation() 
    547920        { 
     
    549922        } 
    550923 
    551924        /** 
    552          * Get the name of the function that called wpdb. 
    553          * @return string the name of the calling function 
     925         * Retrieve the name of the function that called wpdb. 
     926         * 
     927         * Requires PHP 4.3 and searches up the list of functions until it reaches 
     928         * the one that would most logically had called this method. 
     929         * 
     930         * @since 2.5.0 
     931         * 
     932         * @return string The name of the calling function 
    554933         */ 
    555934        function get_caller() { 
    556935                // requires PHP 4.3+ 
     
    578957 
    579958} 
    580959 
    581 if ( ! isset($wpdb) ) 
     960if ( ! isset($wpdb) ) { 
     961        /** 
     962         * WordPress Database Object, if it isn't set already in wp-content/wpdb.php 
     963         * @global object $wpdb Creates a new wpdb object based on wp-config.php Constants for the database 
     964         * @since 0.71 
     965         */ 
    582966        $wpdb = new wpdb(DB_USER, DB_PASSWORD, DB_NAME, DB_HOST); 
     967} 
    583968?>