WordPress.org
Get WordPress

Make WordPress Core


Ignore:
Timestamp:
06/22/2008 08:23:23 PM (17 years ago)
Author:
ryan
Message:

phpdoc updates from jacobsantos. see #7038

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/wp-includes/wp-db.php

    r8134 r8164  
    11<?php
    2 //  WordPress DB Class
    3 
    4 //  ORIGINAL CODE FROM:
    5 //  Justin Vincent (justin@visunet.ie)
    6 //  http://php.justinvincent.com
    7 
     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 */
     11
     12/**
     13 * @since 0.71
     14 */
    815define('EZSQL_VERSION', 'WP1.25');
     16
     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) {
    … …  
    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"));
    … …  
    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
    … …  
    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) {
    … …  
    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
    … …  
    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     */
    … …  
    168449
    169450    /**
    170      * Prepares a SQL query for safe use, using sprintf() syntax
    171      */
    172     function prepare($args=NULL) {
    173         if ( NULL === $args )
     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
     459     */
     460    function prepare($args=null) {
     461        if ( is_null( $args ) )
    174462            return;
    175463        $args = func_get_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 )
    … …  
    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;
    … …  
    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;
    … …  
    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;
    … …  
    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();
    … …  
    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 )
    … …  
    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) {
    … …  
    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){
    … …  
    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) {
    … …  
    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) {
    … …  
    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) {
    … …  
    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) {
    … …  
    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) {
    … …  
    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() {
    … …  
    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() {
    … …  
    514874    /**
    515875     * Wraps fatal errors in a nice header and footer and dies.
     876     *
     877     * @since 1.5.0
     878     *
    516879     * @param string $message
    517      */
    518     function bail($message) { // Just wraps errors in a nice header and footer
     880     * @return unknown
     881     */
     882    function bail($message) {
    519883        if ( !$this->show_errors ) {
    520884            if ( class_exists('WP_Error') )
    … …  
    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()
    … …  
    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()
    … …  
    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() {
    … …  
    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?>
Note: See TracChangeset for help on using the changeset viewer.