WordPress.org
Get WordPress

Make WordPress Core


Ignore:
Timestamp:
07/02/2008 11:07:56 PM (18 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.