WordPress.org
Get WordPress

Make WordPress Core

Changeset 13343


Ignore:
Timestamp:
02/23/2010 10:04:29 PM (15 years ago)
Author:
nacin
Message:

More wpdb cleanups, docs. see #11644 props hakre

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r13341 r13343  
    9494     *
    9595     * @since 1.2
     96     * @access private
    9697     * @var int
    9798     */
    … …  
    102103     *
    103104     * @since 0.71
     105     * @access private
    104106     * @var int
    105107     */
    … …  
    119121     *
    120122     * @since {@internal Version Unknown}}
    121      * @var mixed
     123     * @access private
     124     * @var array|null
    122125     */
    123126    var $last_result;
    … …  
    167170     *
    168171     * @since 3.0.0
     172     * @access public
    169173     * @var int
    170174     */
    … …  
    175179     *
    176180     * @since 3.0.0
     181     * @access public
    177182     * @var int
    178183     */
    179184    var $siteid = 0;
    180 
    181     /**
    182      * WordPress Posts table
    183      *
    184      * @since 1.5.0
    185      * @access public
    186      * @var string
    187      */
    188     var $posts;
    189 
    190     /**
    191      * WordPress Users table
    192      *
    193      * @since 1.5.0
    194      * @access public
    195      * @var string
    196      */
    197     var $users;
    198 
    199     /**
    200      * WordPress Comments table
    201      *
    202      * @since 1.5.0
    203      * @access public
    204      * @var string
    205      */
    206     var $comments;
    207 
    208     /**
    209      * WordPress Links table
    210      *
    211      * @since 1.5.0
    212      * @access public
    213      * @var string
    214      */
    215     var $links;
    216 
    217     /**
    218      * WordPress Options table
    219      *
    220      * @since 1.5.0
    221      * @access public
    222      * @var string
    223      */
    224     var $options;
    225 
    226     /**
    227      * WordPress Post Metadata table
    228      *
    229      * @since {@internal Version Unknown}}
    230      * @access public
    231      * @var string
    232      */
    233     var $postmeta;
    234 
    235     /**
    236      * WordPress Comment Metadata table
    237      *
    238      * @since 2.9
    239      * @access public
    240      * @var string
    241      */
    242     var $commentmeta;
    243 
    244     /**
    245      * WordPress User Metadata table
    246      *
    247      * @since 2.3.0
    248      * @access public
    249      * @var string
    250      */
    251     var $usermeta;
    252 
    253     /**
    254      * WordPress Terms table
    255      *
    256      * @since 2.3.0
    257      * @access public
    258      * @var string
    259      */
    260     var $terms;
    261 
    262     /**
    263      * WordPress Term Taxonomy table
    264      *
    265      * @since 2.3.0
    266      * @access public
    267      * @var string
    268      */
    269     var $term_taxonomy;
    270 
    271     /**
    272      * WordPress Term Relationships table
    273      *
    274      * @since 2.3.0
    275      * @access public
    276      * @var string
    277      */
    278     var $term_relationships;
    279185
    280186    /**
    … …  
    292198     * List of deprecated WordPress tables
    293199     *
    294      * @deprecated
     200     * categories, post2cat, and link2cat were deprecated in 2.3.0, db version 5539
     201     *
    295202     * @since 2.9.0
    296203     * @access private
    … …  
    301208
    302209    /**
    303      * Multisite Blogs table
    304      *
    305      * @since 3.0.0
    306      * @access public
    307      * @var string
    308      */
    309     var $blogs;
    310 
    311     /**
    312      * Multisite Signups table
    313      *
    314      * @since 3.0.0
    315      * @access public
    316      * @var string
    317      */
    318     var $signups;
    319 
    320     /**
    321      * Multisite Sites table
    322      *
    323      * @since 3.0.0
    324      * @access public
    325      * @var string
    326      */
    327     var $site;
    328 
    329     /**
    330      * Multisite Site Metadata table
    331      *
    332      * @since 3.0.0
    333      * @access public
    334      * @var string
    335      */
    336     var $sitemeta;
    337 
    338     /**
    339      * Multisite Sitewide Terms table
    340      *
    341      * @since 3.0.0
    342      * @access public
    343      * @var string
    344      */
    345     var $sitecategories;
    346 
    347     /**
    348      * Multisite Registration Log table
    349      *
    350      * @since 3.0.0
    351      * @access public
    352      * @var string
    353      */
    354     var $registration_log;
    355 
    356     /**
    357      * Multisite Blog Versions table
    358      *
    359      * @since 3.0.0
    360      * @access public
    361      * @var string
    362      */
    363     var $blog_versions;
    364 
    365     /**
    366210     * List of WordPress global tables
    367211     *
    … …  
    383227    var $ms_global_tables = array( 'blogs', 'signups', 'site', 'sitemeta',
    384228        'sitecategories', 'registration_log', 'blog_versions' );
     229
     230    /**
     231     * WordPress Comments table
     232     *
     233     * @since 1.5.0
     234     * @access public
     235     * @var string
     236     */
     237    var $comments;
     238
     239    /**
     240     * WordPress Comment Metadata table
     241     *
     242     * @since 2.9.0
     243     * @access public
     244     * @var string
     245     */
     246    var $commentmeta;
     247
     248    /**
     249     * WordPress Links table
     250     *
     251     * @since 1.5.0
     252     * @access public
     253     * @var string
     254     */
     255    var $links;
     256
     257    /**
     258     * WordPress Options table
     259     *
     260     * @since 1.5.0
     261     * @access public
     262     * @var string
     263     */
     264    var $options;
     265
     266    /**
     267     * WordPress Post Metadata table
     268     *
     269     * @since {@internal Version Unknown}}
     270     * @access public
     271     * @var string
     272     */
     273    var $postmeta;
     274
     275    /**
     276     * WordPress Posts table
     277     *
     278     * @since 1.5.0
     279     * @access public
     280     * @var string
     281     */
     282    var $posts;
     283
     284    /**
     285     * WordPress Terms table
     286     *
     287     * @since 2.3.0
     288     * @access public
     289     * @var string
     290     */
     291    var $terms;
     292
     293    /**
     294     * WordPress Term Relationships table
     295     *
     296     * @since 2.3.0
     297     * @access public
     298     * @var string
     299     */
     300    var $term_relationships;
     301
     302    /**
     303     * WordPress Term Taxonomy table
     304     *
     305     * @since 2.3.0
     306     * @access public
     307     * @var string
     308     */
     309    var $term_taxonomy;
     310
     311    /*
     312     * Global and Multisite tables
     313     */
     314
     315    /**
     316     * WordPress User Metadata table
     317     *
     318     * @since 2.3.0
     319     * @access public
     320     * @var string
     321     */
     322    var $usermeta;
     323
     324    /**
     325     * WordPress Users table
     326     *
     327     * @since 1.5.0
     328     * @access public
     329     * @var string
     330     */
     331    var $users;
     332
     333    /**
     334     * Multisite Blogs table
     335     *
     336     * @since 3.0.0
     337     * @access public
     338     * @var string
     339     */
     340    var $blogs;
     341
     342    /**
     343     * Multisite Blog Versions table
     344     *
     345     * @since 3.0.0
     346     * @access public
     347     * @var string
     348     */
     349    var $blog_versions;
     350
     351    /**
     352     * Multisite Registration Log table
     353     *
     354     * @since 3.0.0
     355     * @access public
     356     * @var string
     357     */
     358    var $registration_log;
     359
     360    /**
     361     * Multisite Signups table
     362     *
     363     * @since 3.0.0
     364     * @access public
     365     * @var string
     366     */
     367    var $signups;
     368
     369    /**
     370     * Multisite Sites table
     371     *
     372     * @since 3.0.0
     373     * @access public
     374     * @var string
     375     */
     376    var $site;
     377
     378    /**
     379     * Multisite Sitewide Terms table
     380     *
     381     * @since 3.0.0
     382     * @access public
     383     * @var string
     384     */
     385    var $sitecategories;
     386
     387    /**
     388     * Multisite Site Metadata table
     389     *
     390     * @since 3.0.0
     391     * @access public
     392     * @var string
     393     */
     394    var $sitemeta;
    385395
    386396    /**
    … …  
    548558        if ( isset( $this->base_prefix ) )
    549559            $old_prefix = $this->base_prefix;
     560
    550561        $this->base_prefix = $prefix;
     562
    551563        foreach ( $this->tables( 'global' ) as $table => $prefixed_table )
    552564            $this->$table = $prefixed_table;
    … …  
    571583     * @since 3.0.0
    572584     * @access public
    573      * @param string $blog_id
    574      * @param string $site_id. Optional.
     585     * @param int $blog_id
     586     * @param int $site_id Optional.
    575587     * @return string previous blog id
    576588     */
    577     function set_blog_id( $blog_id, $site_id = '' ) {
     589    function set_blog_id( $blog_id, $site_id = 0 ) {
    578590        if ( ! empty( $site_id ) )
    579591            $this->siteid = $site_id;
    … …  
    598610     * @uses is_multisite()
    599611     * @since 3.0.0
    600      * @param int $blog_id. Optional.
     612     * @param int $blog_id Optional.
    601613     * @return string Blog prefix.
    602614     */
    603615    function get_blog_prefix( $blog_id = 0 ) {
    604616        if ( is_multisite() && $blog_id ) {
    605             if ( defined('MULTISITE') && ( $blog_id == 0 || $blog_id == 1 ) )
     617            if ( defined( 'MULTISITE' ) && ( 0 == $blog_id || 1 == $blog_id ) )
    606618                return $this->base_prefix;
    607619            else
    … …  
    620632     *
    621633     * @since 3.0.0
    622      * @uses wpdb::tables
    623      * @uses wpdb::old_tables
    624      * @uses wpdb::global_tables
    625      * @uses wpdb::ms_global_tables
     634     * @uses wpdb::$tables
     635     * @uses wpdb::$old_tables
     636     * @uses wpdb::$global_tables
     637     * @uses wpdb::$ms_global_tables
    626638     * @uses is_multisite()
    627639     *
    628      * @param string $scope Can be all, global, ms_global, blog, or old tables. Default all.
    629      *  All returns the blog tables for the queried blog and all global tables.
     640     * @param string $scope Can be all, global, ms_global, blog, or old tables. Defaults to all.
     641     *  'all' returns 'all' and 'global' tables. No old tables are returned.
     642     *  'global' returns the global tables for the installation, returning multisite tables only if running multisite.
     643     *  'ms_global' returns the multisite global tables, regardless if current installation is multisite.
     644     *  'blog' returns the blog-level tables for the queried blog.
     645     *  'old' returns tables which are deprecated.
    630646     * @param bool $prefix Whether to include table prefixes. Default true. If blog
    631      *  prefix is requested, then the custom users and usermeta tables will be mapped.
     647     *  prefix is requested, then the custom users and usermeta tables will be mapped.
    632648     * @param int $blog_id The blog_id to prefix. Defaults to wpdb::blogid. Used only when prefix is requested.
    633649     * @return array Table names. When a prefix is requested, the key is the unprefixed table name.
    … …  
    659675            if ( ! $blog_id )
    660676                $blog_id = $this->blogid;
    661             $prefix = $this->get_blog_prefix( $blog_id );
     677            $blog_prefix = $this->get_blog_prefix( $blog_id );
    662678            $base_prefix = $this->base_prefix;
    663679            $global_tables = array_merge( $this->global_tables, $this->ms_global_tables );
    … …  
    666682                    $tables[ $table ] = $base_prefix . $table;
    667683                else
    668                     $tables[ $table ] = $prefix . $table;
     684                    $tables[ $table ] = $blog_prefix . $table;
    669685                unset( $tables[ $k ] );
    670686            }
    … …  
    710726     * Weak escape
    711727     *
    712      * @see addslashes()
    713      * @since  unknown
     728     * @uses addslashes()
     729     * @since {@internal Version Unknown}}
    714730     * @access private
    715731     *
    … …  
    724740     * Real escape
    725741     *
    726      * @see mysql_real_escape_string()
    727      * @see addslashes()
     742     * @uses mysql_real_escape_string()
     743     * @uses addslashes()
    728744     * @since 2.8
    729745     * @access private
    … …  
    740756
    741757    /**
    742      * Escape data.
    743      *
    744      * @see esc_sql()
     758     * Escape data. Works on arrays.
     759     *
     760     * @uses wpdb::_escape()
     761     * @uses wpdb::_real_escape()
    745762     * @since  2.8
    746763     * @access private
    … …  
    765782
    766783    /**
    767      * Escapes content for insertion into the database using addslashes(), for security
    768      *
    769      * @since 0.71
    770      *
     784     * Escapes content for insertion into the database using addslashes(), for security.
     785     *
     786     * Works on arrays.
     787     *
     788     * @since 0.71
    771789     * @param  string|array $data to escape
    772790     * @return string|array escaped as query safe string
    … …  
    790808     * Escapes content by reference for insertion into the database, for security
    791809     *
     810     * @uses wpdb::_real_escape()
    792811     * @since 2.3.0
    793      *
    794812     * @param  string $string to escape
    795813     * @return void
    … …  
    820838     *
    821839     * <code>
    822      * wpdb::prepare( "SELECT * FROM `table` WHERE `column` = %s AND `field` = %d", "foo", 1337 )
     840     * wpdb::prepare( "SELECT * FROM `table` WHERE `column` = %s AND `field` = %d", 'foo', 1337 )
     841     * wpdb::prepare( "SELECT DATE_FORMAT(`field`, '%%c') FROM `table` WHERE `column` = %s", 'foo' );
    823842     * </code>
    824843     *
    … …  
    838857        if ( is_null( $query ) )
    839858            return;
     859
    840860        $args = func_get_args();
    841861        array_shift( $args );
    … …  
    874894            $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);
    875895
    876         $log_error = true;
    877         if ( ! function_exists('error_log') )
    878             $log_error = false;
    879 
    880         $log_file = @ini_get('error_log');
    881         if ( !empty($log_file) && ('syslog' != $log_file) && !@is_writable($log_file) )
    882             $log_error = false;
    883 
    884         if ( $log_error )
    885             @error_log($error_str, 0);
     896        if ( function_exists('error_log') && $log_file = @ini_get('error_log') && ( 'syslog' == $log_file || is_writable( $log_file ) ) )
     897            @error_log( $error_str, 0 );
    886898
    887899        // Is error output turned on or not..
    888         if ( !$this->show_errors )
     900        if ( ! $this->show_errors )
    889901            return false;
    890902
    … …  
    895907                error_log( $msg, 3, ERRORLOGFILE );
    896908            if ( defined( 'DIEONDBERROR' ) )
    897                 die( $msg );
     909                wp_die( $msg );
    898910        } else {
    899911            $str   = htmlspecialchars( $str, ENT_QUOTES );
    … …  
    10221034            return false;
    10231035
    1024         // filter the query, if filters are available
    1025         // NOTE: some queries are made before the plugins have been loaded, and thus cannot be filtered with this method
     1036        // some queries are made before the plugins have been loaded, and thus cannot be filtered with this method
    10261037        if ( function_exists( 'apply_filters' ) )
    10271038            $query = apply_filters( 'query', $query );
    10281039
    1029         // initialize return
    10301040        $return_val = 0;
    10311041        $this->flush();
    … …  
    10661076
    10671077        $this->result = @mysql_query( $query, $dbh );
    1068         ++$this->num_queries;
    1069 
    1070         if ( defined('SAVEQUERIES') && SAVEQUERIES )
     1078        $this->num_queries++;
     1079
     1080        if ( defined( 'SAVEQUERIES' ) && SAVEQUERIES )
    10711081            $this->queries[] = array( $query, $this->timer_stop(), $this->get_caller() );
    10721082
    … …  
    11121122     *
    11131123     * <code>
     1124     * wpdb::insert( 'table', array( 'column' => 'foo', 'field' => 'bar' ) )
    11141125     * wpdb::insert( 'table', array( 'column' => 'foo', 'field' => 1337 ), array( '%s', '%d' ) )
    11151126     * </code>
    … …  
    11171128     * @since 2.5.0
    11181129     * @see wpdb::prepare()
     1130     * @see wpdb::$field_types
     1131     * @see wp_set_wpdb_vars()
    11191132     *
    11201133     * @param string $table table name
    11211134     * @param array $data Data to insert (in column => value pairs).  Both $data columns and $data values should be "raw" (neither should be SQL escaped).
    1122      * @param array|string $format (optional) An array of formats to be mapped to each of the value in $data.  If string, that format will be used for all of the values in $data.  A format is one of '%d', '%s' (decimal number, string).  If omitted, all values in $data will be treated as strings.
     1135     * @param array|string $format Optional. An array of formats to be mapped to each of the value in $data. If string, that format will be used for all of the values in $data.
     1136     *  A format is one of '%d', '%s' (decimal number, string). If omitted, all values in $data will be treated as strings unless otherwise specified in wpdb::$field_types.
    11231137     * @return int|false The number of rows inserted, or false on error.
    11241138     */
    … …  
    11451159     *
    11461160     * <code>
     1161     * wpdb::update( 'table', array( 'column' => 'foo', 'field' => 'bar' ), array( 'ID' => 1 ) )
    11471162     * wpdb::update( 'table', array( 'column' => 'foo', 'field' => 1337 ), array( 'ID' => 1 ), array( '%s', '%d' ), array( '%d' ) )
    11481163     * </code>
    … …  
    11501165     * @since 2.5.0
    11511166     * @see wpdb::prepare()
     1167     * @see wpdb::$field_types
     1168     * @see wp_set_wpdb_vars()
    11521169     *
    11531170     * @param string $table table name
    1154      * @param array $data Data to update (in column => value pairs).  Both $data columns and $data values should be "raw" (neither should be SQL escaped).
    1155      * @param array $where A named array of WHERE clauses (in column => value pairs).  Multiple clauses will be joined with ANDs.  Both $where columns and $where values should be "raw".
    1156      * @param array|string $format (optional) An array of formats to be mapped to each of the values in $data.  If string, that format will be used for all of the values in $data.  A format is one of '%d', '%s' (decimal number, string).  If omitted, all values in $data will be treated as strings.
    1157      * @param array|string $format_where (optional) An array of formats to be mapped to each of the values in $where.  If string, that format will be used for all of  the items in $where.  A format is one of '%d', '%s' (decimal number, string).  If omitted, all values in $where will be treated as strings.
     1171     * @param array $data Data to update (in column => value pairs). Both $data columns and $data values should be "raw" (neither should be SQL escaped).
     1172     * @param array $where A named array of WHERE clauses (in column => value pairs). Multiple clauses will be joined with ANDs. Both $where columns and $where values should be "raw".
     1173     * @param array|string $format Optional. An array of formats to be mapped to each of the values in $data. If string, that format will be used for all of the values in $data.
     1174     *  A format is one of '%d', '%s' (decimal number, string). If omitted, all values in $data will be treated as strings unless otherwise specified in wpdb::$field_types.
     1175     * @param array|string $format_where Optional. An array of formats to be mapped to each of the values in $where. If string, that format will be used for all of the items in $where.  A format is one of '%d', '%s' (decimal number, string).  If omitted, all values in $where will be treated as strings.
    11581176     * @return int|false The number of rows updated, or false on error.
    11591177     */
    11601178    function update( $table, $data, $where, $format = null, $where_format = null ) {
    1161         if ( ! is_array( $where ) )
     1179        if ( ! is_array( $data ) || ! is_array( $where ) )
    11621180            return false;
    11631181
    … …  
    11981216     * @since 0.71
    11991217     *
    1200      * @param string|null $query Optional. SQL query. If null (default), uses the result from the previous query.
    1201      * @param int $x (optional) Column of value to return.  Indexed from 0.
    1202      * @param int $y (optional) Row of value to return.  Indexed from 0.
    1203      * @return string|null Database query result, or null on failure
     1218     * @param string|null $query Optional. SQL query. Defaults to null, use the result from the previous query.
     1219     * @param int $x Optional. Column of value to return.  Indexed from 0.
     1220     * @param int $y Optional. Row of value to return.  Indexed from 0.
     1221     * @return string|null Database query result (as string), or null on failure
    12041222     */
    12051223    function get_var( $query = null, $x = 0, $y = 0 ) {
    … …  
    12251243     *
    12261244     * @param string|null $query SQL query.
    1227      * @param string $output (optional) one of ARRAY_A | ARRAY_N | OBJECT constants.  Return an associative array (column => value, ...), a numerically indexed array (0 => value, ...) or an object ( ->column = value ), respectively.
    1228      * @param int $y (optional) Row to return.  Indexed from 0.
     1245     * @param string $output Optional. one of ARRAY_A | ARRAY_N | OBJECT constants. Return an associative array (column => value, ...),
     1246     *  a numerically indexed array (0 => value, ...) or an object ( ->column = value ), respectively.
     1247     * @param int $y Optional. Row to return. Indexed from 0.
    12291248     * @return mixed Database query result in format specifed by $output or null on failure
    12301249     */
    … …  
    12591278     * @since 0.71
    12601279     *
    1261      * @param string|null $query Optional. SQL query. If null (default), use the result from the previous query.
     1280     * @param string|null $query Optional. SQL query. Defaults to previous query.
    12621281     * @param int $x Optional. Column to return. Indexed from 0.
    12631282     * @return array Database query result. Array indexed from 0 by SQL result row number.
    … …  
    12831302     *
    12841303     * @param string $query SQL query.
    1285      * @param string $output (optional) ane of ARRAY_A | ARRAY_N | OBJECT | OBJECT_K constants.  With one of the first three, return an array of rows indexed from 0 by SQL result row number.  Each row is an associative array (column => value, ...), a numerically indexed array (0 => value, ...), or an object. ( ->column = value ), respectively.  With OBJECT_K, return an associative array of row objects keyed by the value of each row's first column's value.  Duplicate keys are discarded.
     1304     * @param string $output Optional. Any of ARRAY_A | ARRAY_N | OBJECT | OBJECT_K constants. With one of the first three, return an array of rows indexed from 0 by SQL result row number.
     1305     *  Each row is an associative array (column => value, ...), a numerically indexed array (0 => value, ...), or an object. ( ->column = value ), respectively.
     1306     *  With OBJECT_K, return an associative array of row objects keyed by the value of each row's first column's value.  Duplicate keys are discarded.
    12861307     * @return mixed Database query results
    12871308     */
    … …  
    13861407     *
    13871408     * @param string $message The Error message
    1388      * @param string $error_code (optional) A Computer readable string to identify the error.
     1409     * @param string $error_code Optional. A Computer readable string to identify the error.
    13891410     * @return false|void
    13901411     */
    … …  
    14371458     * @param string $db_cap the feature
    14381459     * @param false|string|resource $dbh_or_table. Not implemented.
    1439      *  Which database to test. False = the currently selected database, string = the database containing the specified table, resource = the database corresponding to the specified mysql resource.
    14401460     * @return bool
    14411461     */
    … …  
    14641484     */
    14651485    function get_caller() {
    1466         $bt = debug_backtrace();
     1486        $trace  = array_reverse( debug_backtrace() );
    14671487        $caller = array();
    14681488
    1469         $bt = array_reverse( $bt );
    1470         foreach ( (array) $bt as $call ) {
     1489        foreach ( $trace as $call ) {
    14711490            if ( isset( $call['class'] ) && __CLASS__ == $call['class'] )
    1472                 continue;
    1473             $function = $call['function'];
    1474             if ( isset( $call['class'] ) )
    1475                 $function = $call['class'] . "->$function";
    1476             $caller[] = $function;
     1491                continue; // Filter out wpdb calls.
    14771492        }
    14781493        $caller = join( ', ', $caller );
    … …  
    14821497
    14831498    /**
    1484      * The database version number
     1499     * The database version number.
     1500     *
    14851501     * @param false|string|resource $dbh_or_table. Not implemented.
    1486      *  Which database to test. False = the currently selected database, string = the database containing the specified table, resource = the database corresponding to the specified mysql resource.
    14871502     * @return false|string false on failure, version number on success
    14881503     */
Note: See TracChangeset for help on using the changeset viewer.