Make WordPress Core


Ignore:
Timestamp:
02/23/2010 10:04:29 PM (17 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.