WordPress.org
Get WordPress

Make WordPress Core


Ignore:
Timestamp:
07/02/2008 11:07:56 PM (17 years ago)
Author:
mdawaffe
Message:

crazyhorse: merge with log:trunk@8151:8240

File:
1 edited

Legend:

Unmodified
Added
Removed

  • branches/crazyhorse/wp-includes/wp-db.php

    r8151 r8242  
    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"));
    … …  
    67318        $this->dbh = @mysql_connect($dbhost, $dbuser, $dbpassword, true);
    68319        if (!$this->dbh) {
    69             $this->bail("
     320            $this->bail(sprintf(/*WP_I18N_DB_CONN_ERROR*/"
    70321<h1>Error establishing a database connection</h1>
    71 <p>This either means that the username and password information in your <code>wp-config.php</code> file is incorrect or we can't contact the database server at <code>$dbhost</code>. This could mean your host's database server is down.</p>
     322<p>This either means that the username and password information in your <code>wp-config.php</code> file is incorrect or we can't contact the database server at <code>%s</code>. This could mean your host's database server is down.</p>
    72323<ul>
    73324    <li>Are you sure you have the correct username and password?</li>
    … …  
    76327</ul>
    77328<p>If you're unsure what these terms mean you should probably contact your host. If you still need help you can always visit the <a href='http://wordpress.org/support/'>WordPress Support Forums</a>.</p>
    78 ");
     329"/*/WP_I18N_DB_CONN_ERROR*/, $dbhost));
    79330            return;
    80331        }
    … …  
    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) )
    107             return new WP_Error('invalid_db_prefix', 'Invalid database prefix'); // No gettext here
     376            return new WP_Error('invalid_db_prefix', /*WP_I18N_DB_BAD_PREFIX*/'Invalid database prefix'/*/WP_I18N_DB_BAD_PREFIX*/);
    108377
    109378        $old_prefix = $this->prefix;
    … …  
    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)) {
    130406            $this->ready = false;
    131             $this->bail("
     407            $this->bail(sprintf(/*WP_I18N_DB_SELECT_DB*/'
    132408<h1>Can&#8217;t select database</h1>
    133 <p>We were able to connect to the database server (which means your username and password is okay) but not able to select the <code>$db</code> database.</p>
     409<p>We were able to connect to the database server (which means your username and password is okay) but not able to select the <code>%1$s</code> database.</p>
    134410<ul>
    135411<li>Are you sure it exists?</li>
    136 <li>Does the user <code>".DB_USER."</code> have permission to use the <code>$db</code> database?</li>
     412<li>Does the user <code>%2$s</code> have permission to use the <code>%1$s</code> database?</li>
    137413<li>On some systems the name of your database is prefixed with your username, so it would be like username_wordpress. Could that be the problem?</li>
    138414</ul>
    139 <p>If you don't know how to setup a database you should <strong>contact your host</strong>. If all else fails you may find help at the <a href='http://wordpress.org/support/'>WordPress Support Forums</a>.</p>");
     415<p>If you don\'t know how to setup a database you should <strong>contact your host</strong>. If all else fails you may find help at the <a href="http://wordpress.org/support/">WordPress Support Forums</a>.</p>'/*/WP_I18N_DB_SELECT_DB*/, $db, DB_USER));
    140416            return;
    141417        }
    … …  
    144420    /**
    145421     * Escapes content for insertion into the database, for security
     422     *
     423     * @since 0.71
    146424     *
    147425     * @param string $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 )
    195488            return false;
    196489
    197         $error_str = "WordPress database error $str for query $this->last_query";
    198490        if ( $caller = $this->get_caller() )
    199             $error_str .= " made by $caller";
     491            $error_str = sprintf(/*WP_I18N_DB_QUERY_ERROR_FULL*/'WordPress database error %1$s for query %2$s made by %3$s'/*/WP_I18N_DB_QUERY_ERROR_FULL*/, $str, $this->last_query, $caller);
     492        else
     493            $error_str = sprintf(/*WP_I18N_DB_QUERY_ERROR*/'WordPress database error %1$s for query %2$s'/*/WP_I18N_DB_QUERY_ERROR*/, $str, $this->last_query);
    200494
    201495        $log_error = true;
    … …  
    224518    }
    225519
    226     // ==================================================================
    227     //  Turn error handling on or off..
    228 
     520    /**
     521     * Enables showing of database errors.
     522     *
     523     * This function should be used only to enable showing of errors.
     524     * wpdb::hide_errors() should be used instead for hiding of errors. However,
     525     * this function can be used to enable and disable showing of database
     526     * errors.
     527     *
     528     * @since 0.71
     529     *
     530     * @param bool $show Whether to show or hide errors
     531     * @return bool Old value for showing errors.
     532     */
    229533    function show_errors( $show = true ) {
    230534        $errors = $this->show_errors;
    … …  
    233537    }
    234538
     539    /**
     540     * Disables showing of database errors.
     541     *
     542     * @since 0.71
     543     *
     544     * @return bool Whether showing of errors was active or not
     545     */
    235546    function hide_errors() {
    236547        $show = $this->show_errors;
    … …  
    239550    }
    240551
     552    /**
     553     * Whether to suppress database errors.
     554     *
     555     * @param unknown_type $suppress
     556     * @return unknown
     557     */
    241558    function suppress_errors( $suppress = true ) {
    242559        $errors = $this->suppress_errors;
    … …  
    245562    }
    246563
    247     // ==================================================================
    248     //  Kill cached query results
    249 
     564    /**
     565     * Kill cached query results.
     566     *
     567     * @since 0.71
     568     */
    250569    function flush() {
    251570        $this->last_result = array();
    … …  
    254573    }
    255574
    256     // ==================================================================
    257     //  Basic Query - see docs for more detail
    258 
     575    /**
     576     * Perform a MySQL database query, using current database connection.
     577     *
     578     * More information can be found on the codex page.
     579     *
     580     * @since 0.71
     581     *
     582     * @param string $query
     583     * @return unknown
     584     */
    259585    function query($query) {
    260586        if ( ! $this->ready )
    … …  
    325651
    326652    /**
    327      * Insert an array of data into a table
     653     * Insert an array of data into a table.
     654     *
     655     * @since 2.5.0
     656     *
    328657     * @param string $table WARNING: not sanitized!
    329      * @param array $data should not already be SQL-escaped
    330      * @return mixed results of $this->query()
     658     * @param array $data Should not already be SQL-escaped
     659     * @return mixed Results of $this->query()
    331660     */
    332661    function insert($table, $data) {
    … …  
    337666
    338667    /**
    339      * Update a row in the table with an array of data
     668     * Update a row in the table with an array of data.
     669     *
     670     * @since 2.5.0
     671     *
    340672     * @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()
     673     * @param array $data Should not already be SQL-escaped
     674     * @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!
     675     * @return mixed Results of $this->query()
    344676     */
    345677    function update($table, $data, $where){
    … …  
    358690
    359691    /**
    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
     692     * Retrieve one variable from the database.
     693     *
     694     * This combines the functionality of wpdb::get_row() and wpdb::get_col(),
     695     * so both the column and row can be picked.
     696     *
     697     * It is possible to use this function without executing more queries. If
     698     * you already made a query, you can set the $query to 'null' value and just
     699     * retrieve either the column and row of the last query result.
     700     *
     701     * @since 0.71
     702     *
     703     * @param string $query Can be null as well, for caching
     704     * @param int $x Column num to return
     705     * @param int $y Row num to return
     706     * @return mixed Database query results
    365707     */
    366708    function get_var($query=null, $x = 0, $y = 0) {
    … …  
    379721
    380722    /**
    381      * Get one row from the database
    382      * @param string $query
     723     * Retrieve one row from the database.
     724     *
     725     * @since 0.71
     726     *
     727     * @param string $query SQL query
    383728     * @param string $output ARRAY_A | ARRAY_N | OBJECT
    384      * @param int $y row num to return
    385      * @return mixed results
     729     * @param int $y Row num to return
     730     * @return mixed Database query results
    386731     */
    387732    function get_row($query = null, $output = OBJECT, $y = 0) {
    … …  
    402747            return $this->last_result[$y] ? array_values(get_object_vars($this->last_result[$y])) : null;
    403748        } else {
    404             $this->print_error(" \$db->get_row(string query, output type, int offset) -- Output type must be one of: OBJECT, ARRAY_A, ARRAY_N");
    405         }
    406     }
    407 
    408     /**
    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
     749            $this->print_error(/*WP_I18N_DB_GETROW_ERROR*/" \$db->get_row(string query, output type, int offset) -- Output type must be one of: OBJECT, ARRAY_A, ARRAY_N"/*/WP_I18N_DB_GETROW_ERROR*/);
     750        }
     751    }
     752
     753    /**
     754     * Retrieve one column from the database.
     755     *
     756     * @since 0.71
     757     *
     758     * @param string $query Can be null as well, for caching
     759     * @param int $x Col num to return. Starts from 0.
     760     * @return array Column results
    413761     */
    414762    function get_col($query = null , $x = 0) {
    … …  
    425773
    426774    /**
    427      * Return an entire result set from the database
    428      * @param string $query (can also be null to pull from the cache)
     775     * Retrieve an entire result set from the database.
     776     *
     777     * @since 0.71
     778     *
     779     * @param string|null $query Can also be null to pull from the cache
    429780     * @param string $output ARRAY_A | ARRAY_N | OBJECT_K | OBJECT
    430      * @return mixed results
     781     * @return mixed Database query results
    431782     */
    432783    function get_results($query = null, $output = OBJECT) {
    … …  
    470821
    471822    /**
    472      * Grabs column metadata from the last query
     823     * Retrieve column metadata from the last query.
     824     *
     825     * @since 0.71
     826     *
    473827     * @param string $info_type one of name, table, def, max_length, not_null, primary_key, multiple_key, unique_key, numeric, blob, type, unsigned, zerofill
    474828     * @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
     829     * @return mixed Column Results
    476830     */
    477831    function get_col_info($info_type = 'name', $col_offset = -1) {
    … …  
    491845
    492846    /**
    493      * Starts the timer, for debugging purposes
     847     * Starts the timer, for debugging purposes.
     848     *
     849     * @since 1.5.0
     850     *
     851     * @return bool Always returns true
    494852     */
    495853    function timer_start() {
    … …  
    501859
    502860    /**
    503      * Stops the debugging timer
    504      * @return int total time spent on the query, in milliseconds
     861     * Stops the debugging timer.
     862     *
     863     * @since 1.5.0
     864     *
     865     * @return int Total time spent on the query, in milliseconds
    505866     */
    506867    function timer_stop() {
    … …  
    514875    /**
    515876     * Wraps fatal errors in a nice header and footer and dies.
     877     *
     878     * @since 1.5.0
     879     *
    516880     * @param string $message
    517      */
    518     function bail($message) { // Just wraps errors in a nice header and footer
     881     * @return unknown
     882     */
     883    function bail($message) {
    519884        if ( !$this->show_errors ) {
    520885            if ( class_exists('WP_Error') )
    … …  
    528893
    529894    /**
    530      * Checks wether of not the database version is high enough to support the features WordPress uses
    531      * @global $wp_version
     895     * Whether or not MySQL database is minimal required version.
     896     *
     897     * @since 2.5.0
     898     * @uses $wp_version
     899     *
     900     * @return WP_Error
    532901     */
    533902    function check_database_version()
    … …  
    541910
    542911    /**
    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.
     912     * Whether of not the database version supports collation.
     913     *
     914     * Called when WordPress is generating the table scheme.
     915     *
     916     * @since 2.5.0
     917     *
     918     * @return bool True if collation is supported, false if version does not
    545919     */
    546920    function supports_collation()
    … …  
    550924
    551925    /**
    552      * Get the name of the function that called wpdb.
    553      * @return string the name of the calling function
     926     * Retrieve the name of the function that called wpdb.
     927     *
     928     * Requires PHP 4.3 and searches up the list of functions until it reaches
     929     * the one that would most logically had called this method.
     930     *
     931     * @since 2.5.0
     932     *
     933     * @return string The name of the calling function
    554934     */
    555935    function get_caller() {
    … …  
    579959}
    580960
    581 if ( ! isset($wpdb) )
     961if ( ! isset($wpdb) ) {
     962    /**
     963     * WordPress Database Object, if it isn't set already in wp-content/wpdb.php
     964     * @global object $wpdb Creates a new wpdb object based on wp-config.php Constants for the database
     965     * @since 0.71
     966     */
    582967    $wpdb = new wpdb(DB_USER, DB_PASSWORD, DB_NAME, DB_HOST);
     968}
    583969?>
Note: See TracChangeset for help on using the changeset viewer.