WordPress 3.3.2-scripts
[autoinstalls/wordpress.git] / wp-includes / wp-db.php
index 61f6d9aab4faa0072b1441bd8a927461c77c9c72..e9ada84dcc02b43f8bc7c027c0e07a7ea22bd612 100644 (file)
@@ -39,16 +39,14 @@ define( 'ARRAY_N', 'ARRAY_N' );
  *
  * It is possible to replace this class with your own
  * by setting the $wpdb global variable in wp-content/db.php
- * file with your class. You can name it wpdb also, since
- * this file will not be included, if the other file is
- * available.
+ * file to your class. The wpdb class will still be included,
+ * so you can extend it or simply use your own.
  *
  * @link http://codex.wordpress.org/Function_Reference/wpdb_Class
  *
  * @package WordPress
  * @subpackage Database
  * @since 0.71
- * @final
  */
 class wpdb {
 
@@ -65,7 +63,7 @@ class wpdb {
         * Whether to suppress errors during the DB bootstrapping.
         *
         * @access private
-        * @since 2.5
+        * @since 2.5.0
         * @var bool
         */
        var $suppress_errors = false;
@@ -73,9 +71,7 @@ class wpdb {
        /**
         * The last error during query.
         *
-        * @see get_last_error()
-        * @since 2.5
-        * @access private
+        * @since 2.5.0
         * @var string
         */
        var $last_error = '';
@@ -92,7 +88,7 @@ class wpdb {
        /**
         * Count of rows returned by previous query
         *
-        * @since 1.2
+        * @since 1.2.0
         * @access private
         * @var int
         */
@@ -456,30 +452,25 @@ class wpdb {
        /**
         * A textual description of the last query/get_row/get_var call
         *
-        * @since unknown
+        * @since 3.0.0
         * @access public
         * @var string
         */
        var $func_call;
 
        /**
-        * Connects to the database server and selects a database
+        * Whether MySQL is used as the database engine.
         *
-        * PHP4 compatibility layer for calling the PHP5 constructor.
+        * Set in WPDB::db_connect() to true, by default. This is used when checking
+        * against the required MySQL version for WordPress. Normally, a replacement
+        * database drop-in (db.php) will skip these checks, but setting this to true
+        * will force the checks to occur.
         *
-        * @uses wpdb::__construct() Passes parameters and returns result
-        * @since 0.71
-        *
-        * @param string $dbuser MySQL database user
-        * @param string $dbpassword MySQL database password
-        * @param string $dbname MySQL database name
-        * @param string $dbhost MySQL database host
+        * @since 3.3.0
+        * @access public
+        * @var bool
         */
-       function wpdb( $dbuser, $dbpassword, $dbname, $dbhost ) {
-               if( defined( 'WP_USE_MULTIPLE_DB' ) && WP_USE_MULTIPLE_DB )
-                       $this->db_connect();
-               return $this->__construct( $dbuser, $dbpassword, $dbname, $dbhost );
-       }
+       public $is_mysql = null;
 
        /**
         * Connects to the database server and selects a database
@@ -502,7 +493,34 @@ class wpdb {
                if ( WP_DEBUG )
                        $this->show_errors();
 
-               if ( is_multisite() ) {
+               $this->init_charset();
+
+               $this->dbuser = $dbuser;
+               $this->dbpassword = $dbpassword;
+               $this->dbname = $dbname;
+               $this->dbhost = $dbhost;
+
+               $this->db_connect();
+       }
+
+       /**
+        * PHP5 style destructor and will run when database object is destroyed.
+        *
+        * @see wpdb::__construct()
+        * @since 2.0.8
+        * @return bool true
+        */
+       function __destruct() {
+               return true;
+       }
+
+       /**
+        * Set $this->charset and $this->collate
+        *
+        * @since 3.1.0
+        */
+       function init_charset() {
+               if ( function_exists('is_multisite') && is_multisite() ) {
                        $this->charset = 'utf8';
                        if ( defined( 'DB_COLLATE' ) && DB_COLLATE )
                                $this->collate = DB_COLLATE;
@@ -514,50 +532,33 @@ class wpdb {
 
                if ( defined( 'DB_CHARSET' ) )
                        $this->charset = DB_CHARSET;
-
-               $this->dbuser = $dbuser;
-
-               $this->dbh = @mysql_connect( $dbhost, $dbuser, $dbpassword, true );
-               if ( !$this->dbh ) {
-                       $this->bail( sprintf( /*WP_I18N_DB_CONN_ERROR*/"
-<h1>Error establishing a database connection</h1>
-<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>
-<ul>
-       <li>Are you sure you have the correct username and password?</li>
-       <li>Are you sure that you have typed the correct hostname?</li>
-       <li>Are you sure that the database server is running?</li>
-</ul>
-<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>
-"/*/WP_I18N_DB_CONN_ERROR*/, $dbhost ), 'db_connect_fail' );
-                       return;
-               }
-
-               $this->ready = true;
-
-               if ( $this->has_cap( 'collation' ) && !empty( $this->charset ) ) {
-                       if ( function_exists( 'mysql_set_charset' ) ) {
-                               mysql_set_charset( $this->charset, $this->dbh );
-                               $this->real_escape = true;
-                       } else {
-                               $query = $this->prepare( 'SET NAMES %s', $this->charset );
-                               if ( ! empty( $this->collate ) )
-                                       $query .= $this->prepare( ' COLLATE %s', $this->collate );
-                               $this->query( $query );
-                       }
-               }
-
-               $this->select( $dbname, $this->dbh );
        }
 
        /**
-        * PHP5 style destructor and will run when database object is destroyed.
+        * Sets the connection's character set.
         *
-        * @see wpdb::__construct()
-        * @since 2.0.8
-        * @return bool true
+        * @since 3.1.0
+        *
+        * @param resource $dbh     The resource given by mysql_connect
+        * @param string   $charset The character set (optional)
+        * @param string   $collate The collation (optional)
         */
-       function __destruct() {
-               return true;
+       function set_charset($dbh, $charset = null, $collate = null) {
+               if ( !isset($charset) )
+                       $charset = $this->charset;
+               if ( !isset($collate) )
+                       $collate = $this->collate;
+               if ( $this->has_cap( 'collation', $dbh ) && !empty( $charset ) ) {
+                       if ( function_exists( 'mysql_set_charset' ) && $this->has_cap( 'set_charset', $dbh ) ) {
+                               mysql_set_charset( $charset, $dbh );
+                               $this->real_escape = true;
+                       } else {
+                               $query = $this->prepare( 'SET NAMES %s', $charset );
+                               if ( ! empty( $collate ) )
+                                       $query .= $this->prepare( ' COLLATE %s', $collate );
+                               mysql_query( $query, $dbh );
+                       }
+               }
        }
 
        /**
@@ -566,6 +567,7 @@ class wpdb {
         * @since 2.5.0
         *
         * @param string $prefix Alphanumeric name for the new prefix.
+        * @param bool $set_table_names Optional. Whether the table names, e.g. wpdb::$posts, should be updated or not.
         * @return string|WP_Error Old prefix or WP_Error on error
         */
        function set_prefix( $prefix, $set_table_names = true ) {
@@ -637,6 +639,7 @@ class wpdb {
                if ( is_multisite() ) {
                        if ( null === $blog_id )
                                $blog_id = $this->blogid;
+                       $blog_id = (int) $blog_id;
                        if ( defined( 'MULTISITE' ) && ( 0 == $blog_id || 1 == $blog_id ) )
                                return $this->base_prefix;
                        else
@@ -650,7 +653,7 @@ class wpdb {
         * Returns an array of WordPress tables.
         *
         * Also allows for the CUSTOM_USER_TABLE and CUSTOM_USER_META_TABLE to
-        * override the WordPress users and usersmeta tables that would otherwise
+        * override the WordPress users and usermeta tables that would otherwise
         * be determined by the prefix.
         *
         * The scope argument can take one of the following:
@@ -736,21 +739,20 @@ class wpdb {
         * @param resource $dbh Optional link identifier.
         * @return null Always null.
         */
-       function select( $db, $dbh = null) {
-               if ( is_null($dbh) ) 
+       function select( $db, $dbh = null ) {
+               if ( is_null($dbh) )
                        $dbh = $this->dbh;
 
                if ( !@mysql_select_db( $db, $dbh ) ) {
                        $this->ready = false;
-                       $this->bail( sprintf( /*WP_I18N_DB_SELECT_DB*/'
-<h1>Can&#8217;t select database</h1>
+                       $this->bail( sprintf( /*WP_I18N_DB_SELECT_DB*/'<h1>Can&#8217;t select database</h1>
 <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>
 <ul>
 <li>Are you sure it exists?</li>
 <li>Does the user <code>%2$s</code> have permission to use the <code>%1$s</code> database?</li>
 <li>On some systems the name of your database is prefixed with your username, so it would be like <code>username_%1$s</code>. Could that be the problem?</li>
 </ul>
-<p>If you don\'t know how to set up 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, $this->dbuser ), 'db_select_fail' );
+<p>If you don\'t know how to set up 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*/, htmlspecialchars( $db, ENT_QUOTES ), htmlspecialchars( $this->dbuser, ENT_QUOTES ) ), 'db_select_fail' );
                        return;
                }
        }
@@ -774,7 +776,7 @@ class wpdb {
         *
         * @see mysql_real_escape_string()
         * @see addslashes()
-        * @since 2.8
+        * @since 2.8.0
         * @access private
         *
         * @param  string $string to escape
@@ -790,9 +792,9 @@ class wpdb {
        /**
         * Escape data. Works on arrays.
         *
-     * @uses wpdb::_escape()
-     * @uses wpdb::_real_escape()
-        * @since  2.8
+        * @uses wpdb::_escape()
+        * @uses wpdb::_real_escape()
+        * @since  2.8.0
         * @access private
         *
         * @param  string|array $data
@@ -853,14 +855,15 @@ class wpdb {
         * Prepares a SQL query for safe execution. Uses sprintf()-like syntax.
         *
         * The following directives can be used in the query format string:
-        *   %d (decimal number)
+        *   %d (integer)
+        *   %f (float)
         *   %s (string)
         *   %% (literal percentage sign - no argument needed)
         *
-        * Both %d and %s are to be left unquoted in the query string and they need an argument passed for them.
+        * All of %d, %f, and %s are to be left unquoted in the query string and they need an argument passed for them.
         * Literals (%) as parts of the query must be properly written as %%.
         *
-        * This function only supports a small subset of the sprintf syntax; it only supports %d (decimal number), %s (string).
+        * This function only supports a small subset of the sprintf syntax; it only supports %d (integer), %f (float), and %s (string).
         * Does not support sign, padding, alignment, width or precision specifiers.
         * Does not support argument numbering/swapping.
         *
@@ -995,7 +998,7 @@ class wpdb {
         * By default database errors are suppressed, with a simple
         * call to this function they can be enabled.
         *
-        * @since 2.5
+        * @since 2.5.0
         * @see wpdb::hide_errors()
         * @param bool $suppress Optional. New value. Defaults to true.
         * @return bool Old value
@@ -1018,28 +1021,22 @@ class wpdb {
                $this->last_query  = null;
        }
 
-       function db_connect( $query = "SELECT" ) {
-               global $db_list, $global_db_list;
-               if ( ! is_array( $db_list ) )
-                       return true;
-
-               if ( $this->blogs != '' && preg_match("/(" . $this->blogs . "|" . $this->users . "|" . $this->usermeta . "|" . $this->site . "|" . $this->sitemeta . "|" . $this->sitecategories . ")/i",$query) ) {
-                       $action = 'global';
-                       $details = $global_db_list[ mt_rand( 0, count( $global_db_list ) -1 ) ];
-                       $this->db_global = $details;
-               } elseif ( preg_match("/^\\s*(alter table|create|insert|delete|update|replace) /i",$query) ) {
-                       $action = 'write';
-                       $details = $db_list[ 'write' ][ mt_rand( 0, count( $db_list[ 'write' ] ) -1 ) ];
-                       $this->db_write = $details;
+       /**
+        * Connect to and select database
+        *
+        * @since 3.0.0
+        */
+       function db_connect() {
+
+               $this->is_mysql = true;
+
+               if ( WP_DEBUG ) {
+                       $this->dbh = mysql_connect( $this->dbhost, $this->dbuser, $this->dbpassword, true );
                } else {
-                       $action = '';
-                       $details = $db_list[ 'read' ][ mt_rand( 0, count( $db_list[ 'read' ] ) -1 ) ];
-                       $this->db_read = $details;
+                       $this->dbh = @mysql_connect( $this->dbhost, $this->dbuser, $this->dbpassword, true );
                }
 
-               $dbhname = "dbh" . $action;
-               $this->$dbhname = @mysql_connect( $details[ 'db_host' ], $details[ 'db_user' ], $details[ 'db_password' ] );
-               if (!$this->$dbhname ) {
+               if ( !$this->dbh ) {
                        $this->bail( sprintf( /*WP_I18N_DB_CONN_ERROR*/"
 <h1>Error establishing a database connection</h1>
 <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>
@@ -1049,9 +1046,16 @@ class wpdb {
        <li>Are you sure that the database server is running?</li>
 </ul>
 <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>
-"/*/WP_I18N_DB_CONN_ERROR*/, $details['db_host'] ), 'db_connect_fail' );
+"/*/WP_I18N_DB_CONN_ERROR*/, htmlspecialchars( $this->dbhost, ENT_QUOTES ) ), 'db_connect_fail' );
+
+                       return;
                }
-               $this->select( $details[ 'db_name' ], $this->$dbhname );
+
+               $this->set_charset( $this->dbh );
+
+               $this->ready = true;
+
+               $this->select( $this->dbname, $this->dbh );
        }
 
        /**
@@ -1084,48 +1088,25 @@ class wpdb {
                if ( defined( 'SAVEQUERIES' ) && SAVEQUERIES )
                        $this->timer_start();
 
-               // use $this->dbh for read ops, and $this->dbhwrite for write ops
-               // use $this->dbhglobal for gloal table ops
-               unset( $dbh );
-               if( defined( 'WP_USE_MULTIPLE_DB' ) && WP_USE_MULTIPLE_DB ) {
-                       if( $this->blogs != '' && preg_match("/(" . $this->blogs . "|" . $this->users . "|" . $this->usermeta . "|" . $this->site . "|" . $this->sitemeta . "|" . $this->sitecategories . ")/i",$query) ) {
-                               if( false == isset( $this->dbhglobal ) ) {
-                                       $this->db_connect( $query );
-                               }
-                               $dbh =& $this->dbhglobal;
-                               $this->last_db_used = "global";
-                       } elseif ( preg_match("/^\\s*(alter table|create|insert|delete|update|replace) /i",$query) ) {
-                               if( false == isset( $this->dbhwrite ) ) {
-                                       $this->db_connect( $query );
-                               }
-                               $dbh =& $this->dbhwrite;
-                               $this->last_db_used = "write";
-                       } else {
-                               $dbh =& $this->dbh;
-                               $this->last_db_used = "read";
-                       }
-               } else {
-                       $dbh =& $this->dbh;
-                       $this->last_db_used = "other/read";
-               }
-
-               $this->result = @mysql_query( $query, $dbh );
+               $this->result = @mysql_query( $query, $this->dbh );
                $this->num_queries++;
 
                if ( defined( 'SAVEQUERIES' ) && SAVEQUERIES )
                        $this->queries[] = array( $query, $this->timer_stop(), $this->get_caller() );
 
                // If there is an error then take note of it..
-               if ( $this->last_error = mysql_error( $dbh ) ) {
+               if ( $this->last_error = mysql_error( $this->dbh ) ) {
                        $this->print_error();
                        return false;
                }
 
-               if ( preg_match( "/^\\s*(insert|delete|update|replace|alter) /i", $query ) ) {
-                       $this->rows_affected = mysql_affected_rows( $dbh );
+               if ( preg_match( '/^\s*(create|alter|truncate|drop) /i', $query ) ) {
+                       $return_val = $this->result;
+               } elseif ( preg_match( '/^\s*(insert|delete|update|replace) /i', $query ) ) {
+                       $this->rows_affected = mysql_affected_rows( $this->dbh );
                        // Take note of the insert_id
-                       if ( preg_match( "/^\\s*(insert|replace) /i", $query ) ) {
-                               $this->insert_id = mysql_insert_id($dbh);
+                       if ( preg_match( '/^\s*(insert|replace) /i', $query ) ) {
+                               $this->insert_id = mysql_insert_id($this->dbh);
                        }
                        // Return number of rows affected
                        $return_val = $this->rows_affected;
@@ -1168,7 +1149,7 @@ class wpdb {
         * @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 unless otherwise specified in wpdb::$field_types.
+        *      A format is one of '%d', '%f', '%s' (integer, float, string). If omitted, all values in $data will be treated as strings unless otherwise specified in wpdb::$field_types.
         * @return int|false The number of rows inserted, or false on error.
         */
        function insert( $table, $data, $format = null ) {
@@ -1191,7 +1172,7 @@ class wpdb {
         * @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 unless otherwise specified in wpdb::$field_types.
+        *      A format is one of '%d', '%f', '%s' (integer, float, string). If omitted, all values in $data will be treated as strings unless otherwise specified in wpdb::$field_types.
         * @return int|false The number of rows affected, or false on error.
         */
        function replace( $table, $data, $format = null ) {
@@ -1212,7 +1193,8 @@ class wpdb {
         * @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 unless otherwise specified in wpdb::$field_types.
+        *      A format is one of '%d', '%f', '%s' (integer, float, string). If omitted, all values in $data will be treated as strings unless otherwise specified in wpdb::$field_types.
+        * @param string $type Optional. What type of operation is this? INSERT or REPLACE. Defaults to INSERT.
         * @return int|false The number of rows affected, or false on error.
         */
        function _insert_replace_helper( $table, $data, $format = null, $type = 'INSERT' ) {
@@ -1251,8 +1233,8 @@ class wpdb {
         * @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 unless otherwise specified in wpdb::$field_types.
-        * @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.
+        *      A format is one of '%d', '%f', '%s' (integer, float, string). If omitted, all values in $data will be treated as strings unless otherwise specified in wpdb::$field_types.
+        * @param array|string $where_format 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', '%f', '%s' (integer, float, 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 ) {
@@ -1325,7 +1307,7 @@ class wpdb {
         * @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
+        * @return mixed Database query result in format specified by $output or null on failure
         */
        function get_row( $query = null, $output = OBJECT, $y = 0 ) {
                $this->func_call = "\$db->get_row(\"$query\",$output,$y)";
@@ -1402,7 +1384,8 @@ class wpdb {
                        // Return an array of row objects with keys from column 1
                        // (Duplicates are discarded)
                        foreach ( $this->last_result as $row ) {
-                               $key = array_shift( $var_by_ref = get_object_vars( $row ) );
+                               $var_by_ref = get_object_vars( $row );
+                               $key = array_shift( $var_by_ref );
                                if ( ! isset( $new_array[ $key ] ) )
                                        $new_array[ $key ] = $row;
                        }
@@ -1531,7 +1514,7 @@ class wpdb {
        /**
         * Determine if a database supports a particular feature
         *
-        * @since 2.7
+        * @since 2.7.0
         * @see   wpdb::db_version()
         *
         * @param string $db_cap the feature
@@ -1545,6 +1528,8 @@ class wpdb {
                        case 'group_concat' : // @since 2.7
                        case 'subqueries' :   // @since 2.7
                                return version_compare( $version, '4.1', '>=' );
+                       case 'set_charset' :
+                               return version_compare($version, '5.0.7', '>=');
                };
 
                return false;
@@ -1576,6 +1561,8 @@ class wpdb {
        /**
         * The database version number.
         *
+        * @since 2.7.0
+        *
         * @return false|string false on failure, version number on success
         */
        function db_version() {
@@ -1583,12 +1570,4 @@ class wpdb {
        }
 }
 
-if ( ! isset( $wpdb ) ) {
-       /**
-        * WordPress Database Object, if it isn't set already in wp-content/db.php
-        * @global object $wpdb Creates a new wpdb object based on wp-config.php Constants for the database
-        * @since 0.71
-        */
-       $wpdb = new wpdb( DB_USER, DB_PASSWORD, DB_NAME, DB_HOST );
-}
 ?>