Index: wp-db.php
===================================================================
--- wp-db.php (revision 13327)
+++ wp-db.php (working copy)
@@ -93,6 +93,7 @@
* Count of rows returned by previous query
*
* @since 1.2
+ * @access private
* @var int
*/
var $num_rows = 0;
@@ -101,6 +102,7 @@
* Count of affected rows by previous query
*
* @since 0.71
+ * @access private
* @var int
*/
var $rows_affected = 0;
@@ -118,7 +120,8 @@
* Results of the last query made
*
* @since {@internal Version Unknown}}
- * @var mixed
+ * @access private
+ * @var array|null
*/
var $last_result;
@@ -166,6 +169,7 @@
* {@internal Missing Description}}
*
* @since 3.0.0
+ * @access private
* @var int
*/
var $blogid = 0;
@@ -174,6 +178,7 @@
* {@internal Missing Description}}
*
* @since 3.0.0
+ * @access private
* @var int
*/
var $siteid = 0;
@@ -290,8 +295,10 @@
/**
* List of deprecated WordPress tables
+ *
+ * - categories, post2cat and link2cat are deprecated
+ * since 2.3.0 / db version >= 5539.
*
- * @deprecated
* @since 2.9.0
* @access private
* @see wpdb::tables()
@@ -460,6 +467,8 @@
* the actual setting up of the class properties and connection
* to the database.
*
+ * NOTE: register_shutdown_function prevents this object from unloading
+ *
* @since 2.0.8
*
* @param string $dbuser MySQL database user
@@ -523,6 +532,14 @@
/**
* PHP5 style destructor and will run when database object is destroyed.
*
+ *
+ * Please see {@link __construct() class constructor} and the
+ * {@link register_shutdown_function() register_shutdown_function()}. for
+ * more details.
+ *
+ * @link http://www.php.net/__destruct
+ * @link http://www.php.net/register_shutdown_function
+ *
* @since 2.0.8
* @return bool true
*/
@@ -547,7 +564,9 @@
if ( isset( $this->base_prefix ) )
$old_prefix = $this->base_prefix;
+
$this->base_prefix = $prefix;
+
foreach ( $this->tables( 'global' ) as $table => $prefixed_table )
$this->$table = $prefixed_table;
@@ -556,12 +575,9 @@
$this->prefix = $this->get_blog_prefix( $this->blogid );
- foreach ( (array) $this->tables( 'blog' ) as $table => $prefixed_table )
+ foreach ( $this->tables( 'blog+old' ) as $table => $prefixed_table )
$this->$table = $prefixed_table;
- foreach ( (array) $this->tables( 'old' ) as $table => $prefixed_table )
- $this->$table = $prefixed_table;
-
return $old_prefix;
}
@@ -571,7 +587,7 @@
* @since 3.0.0
* @access public
* @param string $blog_id
- * @param string $site_id. Optional.
+ * @param string $site_id Optional.
* @return string previous blog id
*/
function set_blog_id( $blog_id, $site_id = '' ) {
@@ -583,12 +599,9 @@
$this->prefix = $this->get_blog_prefix( $this->blogid );
- foreach ( $this->tables( 'blog' ) as $table => $prefixed_table )
+ foreach ( $this->tables( 'blog+old' ) as $table => $prefixed_table )
$this->$table = $prefixed_table;
- foreach ( $this->tables( 'old' ) as $table => $prefixed_table )
- $this->$table = $prefixed_table;
-
return $old_blog_id;
}
@@ -597,12 +610,12 @@
*
* @uses is_multisite()
* @since 3.0.0
- * @param int $blog_id. Optional.
+ * @param int $blog_id Optional.
* @return string Blog prefix.
*/
function get_blog_prefix( $blog_id = 0 ) {
if ( is_multisite() && $blog_id ) {
- if ( defined('MULTISITE') && ( $blog_id == 0 || $blog_id == 1 ) )
+ if ( defined( 'MULTISITE' ) && ( 0 == $blog_id || 1 == $blog_id ) )
return $this->base_prefix;
else
return $this->base_prefix . $blog_id . '_';
@@ -618,51 +631,67 @@
* override the WordPress users and usersmeta tables that would otherwise
* be determined by the prefix.
*
+ * Scope / Table identifiers:
+ * all ........ global and blog tables.
+ * blog ....... blog tables
+ * blog+old ... blog and old (deprecated) tables
+ * global ..... global tables
+ * old ........ old (depreacted) tables
+ *
+ * @access public
* @since 3.0.0
- * @uses wpdb::tables
- * @uses wpdb::old_tables
- * @uses wpdb::global_tables
- * @uses wpdb::ms_global_tables
+ * @uses wpdb::$tables
+ * @uses wpdb::$old_tables
+ * @uses wpdb::$global_tables
+ * @uses wpdb::$ms_global_tables
* @uses is_multisite()
*
- * @param string $scope Can be all, global, blog, or old tables. Default all.
- * All returns the blog tables for the queried blog and all global tables.
- * @param bool $prefix Whether to include table prefixes. Default true. If blog
+ * @param string|array $scope Optional. Scope, Default all. You can pass multiple scopes per array
+ * @param bool $prefix Optional. Whether to include table prefixes. Default true. If blog
* prefix is requested, then the custom users and usermeta tables will be mapped.
* @param int $blog_id The blog_id to prefix. Defaults to main blog. Used only when prefix is requested.
- * @return array Table names. When a prefix is requested, the key is the
- * unprefixed table name.
+ * @return array Table names.
*/
function tables( $scope = 'all', $prefix = true, $blog_id = 0 ) {
- switch ( $scope ) {
- case 'old' :
- $tables = $this->old_tables;
- break;
- case 'blog' :
- $tables = $this->tables;
- break;
- case 'global' :
- $tables = $this->global_tables;
- if ( is_multisite() )
- $tables = array_merge( $tables, $this->ms_global_tables );
- break;
- case 'all' :
- $tables = array_merge( $this->global_tables, $this->tables );
- if ( is_multisite() )
- $tables = array_merge( $tables, $this->ms_global_tables );
- break;
+
+ if ( is_array( $scope ) ) {
+ $tables = array();
+ foreach ( $scope as $each )
+ $tables = array_merge( $tables, $this->tables( $each ) );
+ } else {
+ switch ( $scope ) {
+ case 'old' :
+ $tables = $this->old_tables;
+ break;
+ case 'blog' :
+ $tables = $this->tables;
+ break;
+ case 'blog+old':
+ $tables = array_merge( $this->tables, $this->old_tables );
+ break;
+ case 'global' :
+ $tables = $this->global_tables;
+ if ( is_multisite() )
+ $tables = array_merge( $tables, $this->ms_global_tables );
+ break;
+ case 'all' :
+ $tables = array_merge( $this->global_tables, $this->tables );
+ if ( is_multisite() )
+ $tables = array_merge( $tables, $this->ms_global_tables );
+ break;
+ }
}
- if ( $prefix ) {
- $prefix = $this->get_blog_prefix( $blog_id );
- $base_prefix = $this->base_prefix;
+ if ( count( $tables ) && $prefix ) {
+ $blog_prefix = $this->get_blog_prefix( $blog_id );
+ $base_prefix = $this->base_prefix;
$global_tables = array_merge( $this->global_tables, $this->ms_global_tables );
foreach ( $tables as $k => $table ) {
+ unset( $tables[ $k ] );
if ( in_array( $table, $global_tables ) )
$tables[ $table ] = $base_prefix . $table;
else
- $tables[ $table ] = $prefix . $table;
- unset( $tables[ $k ] );
+ $tables[ $table ] = $blog_prefix . $table;
}
if ( isset( $tables['users'] ) && defined( 'CUSTOM_USER_TABLE' ) )
@@ -705,8 +734,10 @@
/**
* Weak escape
*
+ * An alias to addslashes().
+ *
* @see addslashes()
- * @since unknown
+ * @since {@internal Version Unknown}}
* @access private
*
* @param string $string
@@ -719,6 +750,8 @@
/**
* Real escape
*
+ * Escape via mysql_real_escape_string() or addslashes()
+ *
* @see mysql_real_escape_string()
* @see addslashes()
* @since 2.8
@@ -737,7 +770,9 @@
/**
* Escape data.
*
- * @see esc_sql()
+ * escape data, uses {@see _real_escape()} and works
+ * on arrays as well.
+ *
* @since 2.8
* @access private
*
@@ -816,6 +851,7 @@
*
*
* wpdb::prepare( "SELECT * FROM `table` WHERE `column` = %s AND `field` = %d", "foo", 1337 )
+ * wpdb::prepare( "SELECT DATE_FORMAT(`field`, '%%c') FROM `table` WHERE `column` = %s", 'foo' );
*
*
* @link http://php.net/sprintf Description of syntax.
@@ -833,6 +869,7 @@
function prepare( $query = null ) { // ( $query, *$args )
if ( is_null( $query ) )
return;
+
$args = func_get_args();
array_shift( $args );
// If args were passed as an array (as in vsprintf), move them up
@@ -869,19 +906,14 @@
else
$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);
- $log_error = true;
- if ( ! function_exists('error_log') )
- $log_error = false;
+ if ( function_exists( 'error_log' )
+ && ! ( $log_file = @ini_get( 'error_log' ) )
+ && ( 'syslog' != $log_file )
+ && @is_writable( $log_file ) )
+ @error_log( $error_str );
- $log_file = @ini_get('error_log');
- if ( !empty($log_file) && ('syslog' != $log_file) && !@is_writable($log_file) )
- $log_error = false;
-
- if ( $log_error )
- @error_log($error_str, 0);
-
- // Is error output turned on or not..
- if ( !$this->show_errors )
+ // Show Errors ?
+ if ( ! $this->show_errors )
return false;
// If there is an error then take note of it
@@ -890,7 +922,7 @@
if ( defined( 'ERRORLOGFILE' ) )
error_log( $msg, 3, ERRORLOGFILE );
if ( defined( 'DIEONDBERROR' ) )
- die( $msg );
+ wp_die( $msg );
} else {
$str = htmlspecialchars( $str, ENT_QUOTES );
$query = htmlspecialchars( $this->last_query, ENT_QUOTES );
@@ -1017,12 +1049,9 @@
if ( ! $this->ready )
return false;
- // filter the query, if filters are available
- // NOTE: some queries are made before the plugins have been loaded, and thus cannot be filtered with this method
if ( function_exists( 'apply_filters' ) )
$query = apply_filters( 'query', $query );
- // initialize return
$return_val = 0;
$this->flush();
@@ -1061,9 +1090,9 @@
}
$this->result = @mysql_query( $query, $dbh );
- ++$this->num_queries;
+ $this->num_queries++;
- if ( defined('SAVEQUERIES') && SAVEQUERIES )
+ if ( defined( 'SAVEQUERIES' ) && SAVEQUERIES )
$this->queries[] = array( $query, $this->timer_stop(), $this->get_caller() );
// If there is an error then take note of it..
@@ -1107,6 +1136,7 @@
* Insert a row into a table.
*
*
+ * wpdb::insert( 'table', array( 'column' => 'foo', 'field' => 1337 ) )
* wpdb::insert( 'table', array( 'column' => 'foo', 'field' => 1337 ), array( '%s', '%d' ) )
*
*
@@ -1115,7 +1145,7 @@
*
* @param string $table table name
* @param array $data Data to insert (in column => value pairs). Both $data columns and $data values should be "raw" (neither should be SQL escaped).
- * @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.
+ * @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.
* @return int|false The number of rows inserted, or false on error.
*/
function insert( $table, $data, $format = null ) {
@@ -1140,6 +1170,7 @@
* Update a row in the table
*
*
+ * wpdb::update( 'table', array( 'column' => 'foo', 'field' => 1337 ), array( 'ID' => 1 ) )
* wpdb::update( 'table', array( 'column' => 'foo', 'field' => 1337 ), array( 'ID' => 1 ), array( '%s', '%d' ), array( '%d' ) )
*
*
@@ -1149,12 +1180,12 @@
* @param string $table table name
* @param array $data Data to update (in column => value pairs). Both $data columns and $data values should be "raw" (neither should be SQL escaped).
* @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".
- * @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.
- * @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.
+ * @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.
+ * @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.
* @return int|false The number of rows updated, or false on error.
*/
function update( $table, $data, $where, $format = null, $where_format = null ) {
- if ( ! is_array( $where ) )
+ if ( ! is_array( $data ) || ! is_array( $where ) )
return false;
$formats = $format = (array) $format;
@@ -1193,10 +1224,10 @@
*
* @since 0.71
*
- * @param string|null $query Optional. SQL query. If null (default), uses the result from the previous query.
- * @param int $x (optional) Column of value to return. Indexed from 0.
- * @param int $y (optional) Row of value to return. Indexed from 0.
- * @return string|null Database query result, or null on failure
+ * @param string|null $query Optional. SQL query. Defaults to NULL, use the result from the previous query.
+ * @param int $x Optional. Column of value to return. Indexed from 0.
+ * @param int $y Optional. Row of value to return. Indexed from 0.
+ * @return string|null Database query result (as string), or NULL on failure
*/
function get_var( $query = null, $x = 0, $y = 0 ) {
$this->func_call = "\$db->get_var(\"$query\", $x, $y)";
@@ -1220,9 +1251,9 @@
* @since 0.71
*
* @param string|null $query SQL query.
- * @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.
- * @param int $y (optional) Row to return. Indexed from 0.
- * @return mixed Database query result in format specifed by $output or null on failure
+ * @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.
+ * @param int $y Optional. Row to return. Indexed from 0.
+ * @return mixed Database query result in format specifed by $output or NULL on failure
*/
function get_row( $query = null, $output = OBJECT, $y = 0 ) {
$this->func_call = "\$db->get_row(\"$query\",$output,$y)";
@@ -1254,7 +1285,7 @@
*
* @since 0.71
*
- * @param string|null $query Optional. SQL query. If null (default), use the result from the previous query.
+ * @param string|null $query Optional. SQL query. Defaults to previous query.
* @param int $x Optional. Column to return. Indexed from 0.
* @return array Database query result. Array indexed from 0 by SQL result row number.
*/
@@ -1278,7 +1309,7 @@
* @since 0.71
*
* @param string $query SQL query.
- * @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.
+ * @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.
* @return mixed Database query results
*/
function get_results( $query = null, $output = OBJECT ) {
@@ -1381,7 +1412,7 @@
* @since 1.5.0
*
* @param string $message The Error message
- * @param string $error_code (optional) A Computer readable string to identify the error.
+ * @param string $error_code Optional. A Computer readable string to identify the error.
* @return false|void
*/
function bail( $message, $error_code = '500' ) {
@@ -1459,27 +1490,37 @@
* @return string The name of the calling function
*/
function get_caller() {
- $bt = debug_backtrace();
+ $trace = array_reverse( debug_backtrace() );
$caller = array();
- $bt = array_reverse( $bt );
- foreach ( (array) $bt as $call ) {
+ foreach ( $trace as $call ) {
if ( isset( $call['class'] ) && __CLASS__ == $call['class'] )
- continue;
- $function = $call['function'];
- if ( isset( $call['class'] ) )
- $function = $call['class'] . "->$function";
- $caller[] = $function;
+ continue; # filter out function calls of this object's class
+ $caller[] = isset( $call['class'] ) ? "{$call['class']}->{$call['function']}" : $call['function'];
}
- $caller = join( ', ', $caller );
- return $caller;
+ return join( ', ', $caller );
}
/**
* The database version number
- * @param false|string|resource $dbh_or_table. Not implemented.
- * 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.
+ *
+ * ADDITIONAL PARAMETER NOTICE
+ *
+ * there once was a proposed second parameter which has never been
+ * implemented. It was describben as "Which database to test" ($dbh_or_table)
+ *
+ * It would have had three different types:
+ *
+ * false : currently selected database
+ * string : database containing this table
+ * resource : database by mysql resource
+ *
+ * regarding that third parameter please see {@see db_version()} as well
+ *
+ * @since 2.7
+ * @see has_cap()
+ *
* @return false|string false on failure, version number on success
*/
function db_version() {
@@ -1495,4 +1536,4 @@
*/
$wpdb = new wpdb(DB_USER, DB_PASSWORD, DB_NAME, DB_HOST);
}
-?>
+?>
\ No newline at end of file