WordPress.org

Make WordPress Core

Ticket #7038: wpdb.phpdoc.r8094.diff

File wpdb.phpdoc.r8094.diff, 17.9 KB (added by jacobsantos, 10 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?>