Ticket #11644: 11644.code_cleanup_wpdb.5.patch

wp-db.php

@@ -12 +12 @@
 /**
  * @since 0.71
  */
-define('EZSQL_VERSION', 'WP1.25');
+define( 'EZSQL_VERSION', 'WP1.25' );
 
 /**
  * @since 0.71
  */
-define('OBJECT', 'OBJECT', true);
+define( 'OBJECT', 'OBJECT', true );
 
 /**
  * @since {@internal Version Unknown}}
  */
-define('OBJECT_K', 'OBJECT_K', false);
+define( 'OBJECT_K', 'OBJECT_K', false );
 
 /**
  * @since 0.71
  */
-define('ARRAY_A', 'ARRAY_A', false);
+define( 'ARRAY_A', 'ARRAY_A', false );
 
 /**
  * @since 0.71
  */
-define('ARRAY_N', 'ARRAY_N', false);
+define( 'ARRAY_N', 'ARRAY_N', false );
 
 /**
  * WordPress Database Access Abstraction Object
@@ -65 +65 @@
          * Whether to suppress errors during the DB bootstrapping.
          *
          * @access private
-         * @since {@internal Version Unknown}}
+         * @since 2.5
          * @var bool
          */
         var $suppress_errors = false;
@@ -73 +73 @@
         /**
          * The last error during query.
          *
-         * @since {@internal Version Unknown}}
+         * @see get_last_error()
+         * @since 2.5
+         * @access private
          * @var string
          */
         var $last_error = '';
@@ -88 +90 @@
         var $num_queries = 0;
 
         /**
+         * Amount of rows returned by last query operation
+         *
+         * @since 1.2
+         * @access private
+         * @var int
+         */
+        var $num_rows = 0; 
+
+        /**
+         * Number of affected rows by last query operation
+         *
+         * @since 0.71
+         * @access private
+         * @var integer
+         */
+        var $rows_affected = 0;
+
+
+        /**
          * Saved result of the last query made
          *
          * @since 1.2.0
@@ -97 +118 @@
         var $last_query;
 
         /**
+         * Saved resultset of the last query made
+         *
+         * @since {@internal Version Unknown}
+         * @access private
+         * @var array (null if unintialized)
+         */
+        var $last_result;
+
+        /**
          * Saved info on the table column
          *
          * @since 1.2.0
@@ -135 +165 @@
          * @var bool
          */
         var $ready = false;
+
+        /**
+         * {@internal Missing Description}}
+         *
+         * @since 3.0
+         * @access private
+         * @var unknown_type
+         */
         var $blogid = 0;
+
+        /**
+         * {@internal Missing Description}}
+         *
+         * @since 3.0
+         * @access private
+         * @var unknown_type
+         */
         var $siteid = 0;
 
         /**
@@ -157 +203 @@
         var $users;
 
         /**
+         * WordPress Categories table
+         *
+         * @since 1.5.0
+         * @deprecated 2.3.0 / db version 5539
+         * @access public
+         * @var string
+         */
+        var $categories;
+
+        /**
+         * WordPress Post to Category table
+         *
+         * @since 1.5.0
+         * @deprecated 2.3.0 / db version 5539
+         * @access public
+         * @var string
+         */
+        var $post2cat;
+        
+        /**
+         * WordPress Link to Category table
+         *
+         * @since 1.5.0
+         * @deprecated 2.3.0 / db version 5539
+         * @access public
+         * @var string
+         */
+        var $link2cat;
+
+        /**
          * WordPress Comments table
          *
          * @since 1.5.0
@@ -250 +326 @@
 
         /**
          * List of deprecated WordPress tables
+         * 
+         * - categories, post2cat and link2cat are deprecated 
+         *   since 2.3.0 / db version >= 5539.
          *
          * @since 2.9.0
          * @access private
@@ -406 +485 @@
          * @param string $dbname MySQL database name
          * @param string $dbhost MySQL database host
          */
-        function wpdb($dbuser, $dbpassword, $dbname, $dbhost) {
+        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);
+                return $this->__construct( $dbuser, $dbpassword, $dbname, $dbhost );
         }
 
         /**
@@ -426 +505 @@
          * @param string $dbname MySQL database name
          * @param string $dbhost MySQL database host
          */
-        function __construct($dbuser, $dbpassword, $dbname, $dbhost) {
-                register_shutdown_function(array(&$this, "__destruct"));
+        function __construct( $dbuser, $dbpassword, $dbname, $dbhost ) {
+                register_shutdown_function( array( &$this, '__destruct' ) ); # prevents the object from unloading
 
                 if ( WP_DEBUG )
                         $this->show_errors();
@@ -442 +521 @@
                         $this->collate = DB_COLLATE;
                 }
 
-                if ( defined('DB_CHARSET') )
+                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*/"
+                $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>
@@ -458 +537 @@
         <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');
+"/*/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);
+                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 {
-                                $collation_query = "SET NAMES '{$this->charset}'";
-                                if ( !empty($this->collate) )
-                                        $collation_query .= " COLLATE '{$this->collate}'";
-                                $this->query($collation_query);
+                                $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);
+                $this->select( $dbname, $this->dbh );
         }
 
         /**
          * 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 Always true
+         * @return bool true
          */
         function __destruct() {
                 return true;
@@ -503 +590 @@
          */
         function set_prefix( $prefix ) {
 
-                if ( preg_match('|[^a-z0-9_]|i', $prefix) )
+                if ( preg_match( '|[^a-z0-9_]|i', $prefix ) )
                         return new WP_Error('invalid_db_prefix', /*WP_I18N_DB_BAD_PREFIX*/'Invalid database prefix'/*/WP_I18N_DB_BAD_PREFIX*/);
+                        
+                $old_prefix = is_multisite() ? '' : $prefix;
 
-                if ( is_multisite() )
-                        $old_prefix = '';
-                else
-                        $old_prefix = $prefix;
-
                 if ( isset( $this->base_prefix ) )
                         $old_prefix = $this->base_prefix;
+
                 $this->base_prefix = $prefix;
+
                 foreach ( $this->tables( 'global' ) as $table )
                         $this->$table = $prefix . $table;
 
-                if ( defined('VHOST') && empty( $this->blogid ) )
+                if ( defined( 'VHOST' ) && empty( $this->blogid ) )
                         return $old_prefix;
 
                 $this->prefix = $this->get_blog_prefix( $this->blogid );
 
-                foreach ( (array) $this->tables( 'blog' ) as $table )
+                foreach ( $this->tables( array('blog', 'old' ) ) as $table )
                         $this->$table = $this->prefix . $table;
-
-                foreach ( (array) $this->tables( 'old' ) as $table )
-                        $this->$table = $this->prefix . $table;
-
-                if ( defined('CUSTOM_USER_TABLE') )
+                        
+                if ( defined( 'CUSTOM_USER_TABLE' ) )
                         $this->users = CUSTOM_USER_TABLE;
 
-                if ( defined('CUSTOM_USER_META_TABLE') )
+                if ( defined( 'CUSTOM_USER_META_TABLE' ) )
                         $this->usermeta = CUSTOM_USER_META_TABLE;
 
                 return $old_prefix;
         }
 
-        function set_blog_id($blog_id, $site_id = '') {
+        /**
+         * blog id setter
+         * 
+         * {@internal Missing Description}}
+         *
+         * @since 3.0
+         * @access public
+         * @param string $blog_id
+         * @param string $site_id (optional)
+         * @return string previous blog id
+         */     
+        function set_blog_id( $blog_id, $site_id = '' ) {
                 if ( !empty($site_id) )
                         $this->siteid = $site_id;
 
-                $old_blog_id = $this->blogid;
+                $old_blog_id  = $this->blogid;
                 $this->blogid = $blog_id;
 
                 $this->prefix = $this->get_blog_prefix( $this->blogid );
 
-                foreach ( $this->tables( 'blog' ) as $table )
+                foreach ( $this->tables( array('blog', 'old') ) as $table )
                         $this->$table = $this->prefix . $table;
 
-                foreach ( $this->tables( 'old' ) as $table )
-                        $this->$table = $this->prefix . $table;
-
                 return $old_blog_id;
         }
 
+        /**
+         * blog prefix getter
+         * 
+         * {@internal Missing Description}}
+         * 
+         * @param string $blog_id (optional)
+         * @return unknown_type
+         */
         function get_blog_prefix( $blog_id = '' ) {
                 if ( is_multisite() && $blog_id ) {
                         if ( defined('MULTISITE') && ( $blog_id == 0 || $blog_id == 1 ) )
@@ -569 +668 @@
         /**
          * Returns an array of WordPress tables.
          *
+         * Scope / Table identifiers:
+         * 
+         *   - 'all' ........ global and blog tables.
+         *   - 'global' ..... global tables
+         *   - 'blog' ....... blog tables
+         *   - 'old tables' . old (depreacted) tables
+         *   
+         * NOTE: This function does not reflect CUSTOM_USER_TABLE  
+         *       and CUSTOM_USER_META_TABLE and will return
+         *       the standard table names (users, usermeta) instead.
+         *
+         * @access public
          * @since 3.0.0
-         * @uses wpdb::tables
-         * @uses wpdb::old_tables
-         * @uses wpdb::global_tables
+         * @uses wpdb::$tables
+         * @uses wpdb::$old_tables
+         * @uses wpdb::$global_tables
+         * @uses wpdb::$ms_tables
          * @uses is_multisite()
          *
-         * @param string $scope Can be all, global, blog, or old tables. Default all.
-         *      All returns all global tables and the blog tables for the queried blog.
-         * @param bool $prefix Whether to include the blog prefix. Default false.
-         * @param int $blog_id The blog_id to prefix. Defaults to main blog.
+         * @param string|array $scope (optional) Scope, Default 'all'. You can pass multiple scopes per array
+         * @param bool $prefix (optional) Whether to include the blog prefix. Default FALSE.
+         * @param int $blog_id (optional) The blog_id to prefix.
          * @return array Table names.
          */
-        function tables( $scope = 'all', $prefix = false, $blog_id = 0 ) {
-                switch ( $scope ) {
-                        case 'old' :
-                                $tables = $this->old_tables;
-                                break;
-                        case 'blog' :
-                                $tables = $this->tables;
-                                break;
-                        case 'global' :
-                                $tables = array_merge( $this->global_tables, $this->ms_tables );
-                                break;
-                        case 'all' :
-                                $tables = array_merge( $this->global_tables, $this->tables );
-                                if ( is_multisite() )
-                                        $tables = array_merge( $tables, $this->ms_tables );
-                                break;
+        function tables( $scope = 'all', $prefix = false, $blog_id = '' ) {
+                
+                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 'global' :
+                                        $tables = array_merge( $this->global_tables, $this->ms_tables );
+                                        if ( is_multisite() )
+                                                $tables = array_merge( $tables, $this->ms_tables );
+                                        break;
+                                case 'all' :
+                                        $tables = $this->tables( array( 'global', 'blog' ) );           
+                                        break;
+                        }
                 }
 
-                if ( $prefix ) {
+                if ( count( $tables ) && $prefix ) {
                         $prefix = $this->get_blog_prefix( $blog_id );
-                        foreach ( $tables as $k => $table ) {
+                        foreach ( $tables as $k => $table )
                                 $tables[$k] = $prefix . $table;
-                        }
                 }
 
                 return $tables;
@@ -620 +737 @@
          * @param string $db MySQL database name
          * @return null Always null.
          */
-        function select($db, &$dbh) {
-                if (!@mysql_select_db($db, $dbh)) {
+        function select( $db, &$dbh ) {
+                if ( !@mysql_select_db( $db, $dbh ) ) {
                         $this->ready = false;
-                        $this->bail(sprintf(/*WP_I18N_DB_SELECT_DB*/'
+                        $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>
@@ -631 +748 @@
 <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 setup a database you should <strong>contact your host</strong>. If all else fails you may find help at the <a href="http://wordpress.org/support/">WordPress Support Forums</a>.</p>'/*/WP_I18N_DB_SELECT_DB*/, $db, $this->dbuser), 'db_select_fail');
+<p>If you don\'t know how to setup a database you should <strong>contact your host</strong>. If all else fails you may find help at the <a href="http://wordpress.org/support/">WordPress Support Forums</a>.</p>'/*/WP_I18N_DB_SELECT_DB*/, $db, $this->dbuser ), 'db_select_fail' );
                         return;
                 }
         }
 
-        function _weak_escape($string) {
-                return addslashes($string);
+        /**
+         * weak escape
+         *
+         * an alias to addslashes()
+         *
+         * @see addslashes()
+         *
+         * @since {@internal Version Unknown}}
+         * @access private
+         * @param string $string
+         * @return string
+         */
+        function _weak_escape( $string ) {
+                return addslashes( $string );
         }
 
-        function _real_escape($string) {
+        /**
+         * real escape
+         *
+         * escape via mysql_real_escape_string() or addslashes()  
+         *
+         * @since  2.8
+         * @access private
+         *
+         * @param  string $string to escape
+         * @return string escaped
+         */
+        function _real_escape( $string ) {
                 if ( $this->dbh && $this->real_escape )
                         return mysql_real_escape_string( $string, $this->dbh );
                 else
                         return addslashes( $string );
         }
 
-        function _escape($data) {
-                if ( is_array($data) ) {
+        /**
+         * escape
+         *
+         * escape data, uses {@see _real_escape()} and works 
+         * on arrays as well.
+         *
+         * @since  2.8
+         * @access private
+         * 
+         * @param  string|array $data to escape
+         * @return string|array escaped
+         */
+        function _escape( $data ) {
+                if ( is_array( $data ) ) {
                         foreach ( (array) $data as $k => $v ) {
                                 if ( is_array($v) )
                                         $data[$k] = $this->_escape( $v );
@@ -667 +819 @@
          *
          * @since 0.71
          *
-         * @param string|array $data
-         * @return string query safe string
+         * @param  string|array $data to escape
+         * @return string|array escaped as query safe string
          */
-        function escape($data) {
-                if ( is_array($data) ) {
+        function escape( $data ) {
+                if ( is_array( $data ) ) {
                         foreach ( (array) $data as $k => $v ) {
-                                if ( is_array($v) )
+                                if ( is_array( $v ) )
                                         $data[$k] = $this->escape( $v );
                                 else
                                         $data[$k] = $this->_weak_escape( $v );
@@ -690 +842 @@
          *
          * @since 2.3.0
          *
-         * @param string $s
+         * @param  string $string to escape
+         * @return void
          */
-        function escape_by_ref(&$string) {
+        function escape_by_ref( &$string ) {
                 $string = $this->_real_escape( $string );
         }
 
         /**
          * 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)  
+         *   %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. 
+         * 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).
          * Does not support sign, padding, alignment, width or precision specifiers.
          * Does not support argument numbering/swapping.
@@ -709 +873 @@
          *
          * <code>
          * 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' );
          * </code>
          *
          * @link http://php.net/sprintf Description of syntax.
          * @since 2.3.0
          *
          * @param string $query Query statement with sprintf()-like placeholders
-         * @param array|mixed $args The array of variables to substitute into the query's placeholders if being called like {@link http://php.net/vsprintf vsprintf()}, or the first variable to substitute into the query's placeholders if being called like {@link http://php.net/sprintf sprintf()}.
+         * @param mixed $args The array of variables to substitute into the query's placeholders if being called like {@link http://php.net/vsprintf vsprintf()}, or the first variable to substitute into the query's placeholders if being called like {@link http://php.net/sprintf sprintf()}.
          * @param mixed $args,... further variables to substitute into the query's placeholders if being called like {@link http://php.net/sprintf sprintf()}.
-         * @return null|string Sanitized query string
+         * @return null|false|string Sanitized query string, null if there is no query, false if there is an error and string if there was something to prepare
          */
-        function prepare($query = null) { // ( $query, *$args )
+        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
-                if ( isset($args[0]) && is_array($args[0]) )
-                        $args = $args[0];
-                $query = str_replace("'%s'", '%s', $query); // in case someone mistakenly already singlequoted it
-                $query = str_replace('"%s"', '%s', $query); // doublequote unquoting
-                $query = str_replace('%s', "'%s'", $query); // quote the strings
-                array_walk($args, array(&$this, 'escape_by_ref'));
-                return @vsprintf($query, $args);
+                array_shift( $args );
+                if ( isset( $args[0] ) && is_array( $args[0] ) )
+                        $args = $args[0]; # re-assign args passed as array like in vsprintf
+
+                $query = str_replace( "'%s'", '%s', $query ); // in case someone mistakenly already singlequoted it
+                $query = str_replace( '"%s"', '%s', $query ); // doublequote unquoting
+                $query = str_replace( '%s', "'%s'", $query ); // quote the strings
+                array_walk( $args, array( &$this, 'escape_by_ref' ) );
+                return @vsprintf( $query, $args );
         }
 
         /**
@@ -743 +909 @@
          * @param string $str The error to display
          * @return bool False if the showing of errors is disabled.
          */
-        function print_error($str = '') {
+        function print_error( $str = '' ) {
                 global $EZSQL_ERROR;
 
-                if (!$str) $str = mysql_error($this->dbh);
-                $EZSQL_ERROR[] = array ('query' => $this->last_query, 'error_str' => $str);
+                if ( !$str ) $str = mysql_error( $this->dbh );
+                $EZSQL_ERROR[] = array( 'query' => $this->last_query, 'error_str' => $str );
 
                 if ( $this->suppress_errors )
                         return false;
@@ -757 +923 @@
                 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 )
                         return false;
@@ -778 +939 @@
                         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);
+                        $str   = htmlspecialchars( $str, ENT_QUOTES );
+                        $query = htmlspecialchars( $this->last_query, ENT_QUOTES );
 
                         print "<div id='error'>
                         <p class='wpdberror'><strong>WordPress database error:</strong> [$str]<br />
@@ -799 +960 @@
          * errors.
          *
          * @since 0.71
+         * @see hide_errors()
          *
          * @param bool $show Whether to show or hide errors
          * @return bool Old value for showing errors.
@@ -812 +974 @@
         /**
          * Disables showing of database errors.
          *
+         * By default database errors are not shown.
+         *
          * @since 0.71
+         * @see show_errors()
          *
          * @return bool Whether showing of errors was active or not
          */
@@ -825 +990 @@
         /**
          * Whether to suppress database errors.
          *
-         * @param unknown_type $suppress
-         * @return unknown
+         * By default database errors are suppressed, with a simple
+         * call to this function they can be enabled.
+         *
+         * @since 2.5
+         * @see hide_errors()
+         * @param bool $suppress (optional) new value, defaults to true
+         * @return bool old suppress errors value
          */
         function suppress_errors( $suppress = true ) {
                 $errors = $this->suppress_errors;
-                $this->suppress_errors = $suppress;
+                $this->suppress_errors = (bool) $suppress;
                 return $errors;
         }
 
@@ -838 +1008 @@
          * Kill cached query results.
          *
          * @since 0.71
+         *
+         * @return void
          */
         function flush() {
                 $this->last_result = array();
-                $this->col_info = null;
-                $this->last_query = null;
+                $this->col_info    = null;
+                $this->last_query  = null;
         }
 
         function db_connect( $query = "SELECT" ) {
@@ -865 +1037 @@
                 }
 
                 $dbhname = "dbh" . $action;
-                $this->$dbhname = @mysql_connect( $details[ 'db_host' ], $details[ 'db_user' ], $details[ 'db_password' ] );
+                $this->$dbhname = @mysql_connect( $details[ 'db_host' ], $details[ 'db_user' ], $details[ 'db_password' ] );            
                 if (!$this->$dbhname ) {
-                        $this->bail("
+                        $this->bail( sprintf( /*WP_I18N_DB_CONNECT_DB*/'
 <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>{$details['db_host']}</code>. This could mean your host's database server is down.</p>
+<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>
-");
+<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_CONNECT_DB*/, $dbhost) );
                 }
                 $this->select( $details[ 'db_name' ], $this->$dbhname );
         }
@@ -888 +1059 @@
          *
          * @since 0.71
          *
-         * @param string $query
+         * @param string $query database query
          * @return int|false Number of rows affected/selected or false on error
          */
-        function query($query) {
+        function query( $query ) {
                 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);
+                if ( function_exists( 'apply_filters' ) )
+                        $query = apply_filters( 'query', $query );
 
-                // initialise return
+                // init return values and object's state
                 $return_val = 0;
                 $this->flush();
 
@@ -910 +1079 @@
                 // Keep track of the last query for debug..
                 $this->last_query = $query;
 
-                // Perform the query via std mysql_query function..
-                if ( defined('SAVEQUERIES') && SAVEQUERIES )
+                if ( defined( 'SAVEQUERIES' ) && SAVEQUERIES )
                         $this->timer_start();
 
                 // use $this->dbh for read ops, and $this->dbhwrite for write ops
@@ -939 +1107 @@
                         $this->last_db_used = "other/read";
                 }
 
-                $this->result = @mysql_query($query, $dbh);
-                ++$this->num_queries;
+                // Perform the query via std mysql_query function..
+                $this->result = @mysql_query( $query, $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( $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*(insert|delete|update|replace|alter) /i", $query ) ) {
+                        $this->rows_affected = mysql_affected_rows( $dbh );
                         // Take note of the insert_id
-                        if ( preg_match("/^\\s*(insert|replace) /i",$query) ) {
+                        if ( preg_match( "/^\\s*(insert|replace) /i", $query ) ) {
                                 $this->insert_id = mysql_insert_id($dbh);
                         }
                         // Return number of rows affected
                         $return_val = $this->rows_affected;
                 } else {
                         $i = 0;
-                        while ($i < @mysql_num_fields($this->result)) {
-                                $this->col_info[$i] = @mysql_fetch_field($this->result);
+                        while ( $i < @mysql_num_fields( $this->result ) ) {
+                                $this->col_info[$i] = @mysql_fetch_field( $this->result );
                                 $i++;
                         }
                         $num_rows = 0;
-                        while ( $row = @mysql_fetch_object($this->result) ) {
+                        while ( $row = @mysql_fetch_object( $this->result ) ) {
                                 $this->last_result[$num_rows] = $row;
                                 $num_rows++;
                         }
 
-                        @mysql_free_result($this->result);
+                        @mysql_free_result( $this->result );
 
                         // Log number of rows the query returned
+                        // and Return number of rows selected
                         $this->num_rows = $num_rows;
-
-                        // Return number of rows selected
-                        $return_val = $this->num_rows;
+                        $return_val     = $num_rows;
                 }
 
                 return $return_val;
@@ -987 +1155 @@
          * Insert a row into a table.
          *
          * <code>
+         * wpdb::insert( 'table', array( 'column' => 'foo', 'field' => 1337 ) )
          * wpdb::insert( 'table', array( 'column' => 'foo', 'field' => 1337 ), array( '%s', '%d' ) )
          * </code>
          *
@@ -998 +1167 @@
          * @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) {
+        function insert( $table, $data, $format = null ) {
                 $formats = $format = (array) $format;
-                $fields = array_keys($data);
+                $fields = array_keys( $data );
                 $formatted_fields = array();
                 foreach ( $fields as $field ) {
-                        if ( !empty($format) )
-                                $form = ( $form = array_shift($formats) ) ? $form : $format[0];
-                        elseif ( isset($this->field_types[$field]) )
+                        if ( !empty( $format ) )
+                                $form = ( $form = array_shift( $formats ) ) ? $form : $format[0];
+                        elseif ( isset( $this->field_types[$field] ) )
                                 $form = $this->field_types[$field];
                         else
                                 $form = '%s';
                         $formatted_fields[] = $form;
                 }
                 $sql = "INSERT INTO `$table` (`" . implode( '`,`', $fields ) . "`) VALUES ('" . implode( "','", $formatted_fields ) . "')";
-                return $this->query( $this->prepare( $sql, $data) );
+                return $this->query( $this->prepare( $sql, $data ) );
         }
 
 
@@ -1020 +1189 @@
          * Update a row in the table
          *
          * <code>
+         * 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' ) )
          * </code>
          *
@@ -1033 +1203 @@
          * @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 ) )
+        function update( $table, $data, $where, $format = null, $where_format = null ) {
+                if ( !is_array( $data ) || !is_array( $where ) )
                         return false;
 
                 $formats = $format = (array) $format;
                 $bits = $wheres = array();
-                foreach ( (array) array_keys($data) as $field ) {
-                        if ( !empty($format) )
-                                $form = ( $form = array_shift($formats) ) ? $form : $format[0];
+                foreach ( (array) array_keys( $data ) as $field ) {
+                        if ( !empty( $format ) )
+                                $form = ( $form = array_shift( $formats ) ) ? $form : $format[0];
                         elseif ( isset($this->field_types[$field]) )
                                 $form = $this->field_types[$field];
                         else
@@ -1050 +1220 @@
                 }
 
                 $where_formats = $where_format = (array) $where_format;
-                foreach ( (array) array_keys($where) as $field ) {
-                        if ( !empty($where_format) )
-                                $form = ( $form = array_shift($where_formats) ) ? $form : $where_format[0];
-                        elseif ( isset($this->field_types[$field]) )
+                foreach ( (array) array_keys( $where ) as $field ) {
+                        if ( !empty( $where_format ) )
+                                $form = ( $form = array_shift( $where_formats ) ) ? $form : $where_format[0];
+                        elseif ( isset( $this->field_types[$field] ) )
                                 $form = $this->field_types[$field];
                         else
                                 $form = '%s';
@@ -1061 +1231 @@
                 }
 
                 $sql = "UPDATE `$table` SET " . implode( ', ', $bits ) . ' WHERE ' . implode( ' AND ', $wheres );
-                return $this->query( $this->prepare( $sql, array_merge(array_values($data), array_values($where))) );
+                return $this->query( $this->prepare( $sql, array_merge( array_values( $data ), array_values( $where ) ) ) );
         }
 
         /**
@@ -1073 +1243 @@
          *
          * @since 0.71
          *
-         * @param string|null $query SQL query.  If null, use the result from the previous query.
+         * @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 Database query result
+         * @return string|null Database query result on success (as string), NULL if a value on failure
          */
-        function get_var($query=null, $x = 0, $y = 0) {
-                $this->func_call = "\$db->get_var(\"$query\",$x,$y)";
+        function get_var( $query = null, $x = 0, $y = 0 ) {
+                $this->func_call = "\$db->get_var(\"$query\", $x, $y)";
                 if ( $query )
-                        $this->query($query);
+                        $this->query( $query );
 
                 // Extract var out of cached results based x,y vals
                 if ( !empty( $this->last_result[$y] ) ) {
-                        $values = array_values(get_object_vars($this->last_result[$y]));
+                        $values = array_values( get_object_vars( $this->last_result[$y] ) );
                 }
 
                 // If there is a value return it else return null
-                return (isset($values[$x]) && $values[$x]!=='') ? $values[$x] : null;
+                return ( isset( $values[$x] ) && $values[$x] !== '' ) ? $values[$x] : null;
         }
 
         /**
@@ -1102 +1272 @@
          * @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
+         * @return mixed Database query result in format specifed by $output or NULL
+         * @return void
          */
-        function get_row($query = null, $output = OBJECT, $y = 0) {
+        function get_row( $query = null, $output = OBJECT, $y = 0 ) {
                 $this->func_call = "\$db->get_row(\"$query\",$output,$y)";
                 if ( $query )
-                        $this->query($query);
+                        $this->query( $query );
                 else
                         return null;
 
-                if ( !isset($this->last_result[$y]) )
+                if ( !isset( $this->last_result[$y] ) )
                         return null;
 
                 if ( $output == OBJECT ) {
                         return $this->last_result[$y] ? $this->last_result[$y] : null;
                 } elseif ( $output == ARRAY_A ) {
-                        return $this->last_result[$y] ? get_object_vars($this->last_result[$y]) : null;
+                        return $this->last_result[$y] ? get_object_vars( $this->last_result[$y] ) : null;
                 } elseif ( $output == ARRAY_N ) {
-                        return $this->last_result[$y] ? array_values(get_object_vars($this->last_result[$y])) : null;
+                        return $this->last_result[$y] ? array_values( get_object_vars( $this->last_result[$y] ) ) : null;
                 } else {
                         $this->print_error(/*WP_I18N_DB_GETROW_ERROR*/" \$db->get_row(string query, output type, int offset) -- Output type must be one of: OBJECT, ARRAY_A, ARRAY_N"/*/WP_I18N_DB_GETROW_ERROR*/);
                 }
@@ -1134 +1305 @@
          *
          * @since 0.71
          *
-         * @param string|null $query SQL query.  If null, use the result from the previous query.
-         * @param int $x Column to return.  Indexed from 0.
+         * @param string|null $query (optional) SQL query. If null, use the result from the 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.
          */
-        function get_col($query = null , $x = 0) {
+        function get_col( $query = null , $x = 0 ) {
                 if ( $query )
-                        $this->query($query);
+                        $this->query( $query );
 
                 $new_array = array();
                 // Extract the column values
-                for ( $i=0; $i < count($this->last_result); $i++ ) {
-                        $new_array[$i] = $this->get_var(null, $x, $i);
+                for ( $i=0; $i < count( $this->last_result ); $i++ ) {
+                        $new_array[$i] = $this->get_var( null, $x, $i );
                 }
                 return $new_array;
         }
@@ -1161 +1332 @@
          * @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) {
+        function get_results( $query = null, $output = OBJECT ) {
                 $this->func_call = "\$db->get_results(\"$query\", $output)";
 
                 if ( $query )
-                        $this->query($query);
+                        $this->query( $query );
                 else
                         return null;
 
@@ -1206 +1377 @@
          *
          * @since 0.71
          *
-         * @param string $info_type one of name, table, def, max_length, not_null, primary_key, multiple_key, unique_key, numeric, blob, type, unsigned, zerofill
-         * @param int $col_offset 0: col name. 1: which table the col's in. 2: col's max length. 3: if the col is numeric. 4: col's type
+         * @param string $info_type(optional) type one of name, table, def, max_length, not_null, primary_key, multiple_key, unique_key, numeric, blob, type, unsigned, zerofill
+         * @param int $col_offset (optional) 0: col name. 1: which table the col's in. 2: col's max length. 3: if the col is numeric. 4: col's type
          * @return mixed Column Results
          */
-        function get_col_info($info_type = 'name', $col_offset = -1) {
+        function get_col_info( $info_type = 'name', $col_offset = -1 ) {
                 if ( $this->col_info ) {
                         if ( $col_offset == -1 ) {
-                                $i = 0;
+                                $i         = 0;
                                 $new_array = array();
                                 foreach( (array) $this->col_info as $col ) {
                                         $new_array[$i] = $col->{$info_type};
@@ -1234 +1405 @@
          * @return true
          */
         function timer_start() {
-                $mtime = microtime();
-                $mtime = explode(' ', $mtime);
+                $mtime            = explode( ' ', microtime() );
                 $this->time_start = $mtime[1] + $mtime[0];
                 return true;
         }
@@ -1248 +1418 @@
          * @return int Total time spent on the query, in milliseconds
          */
         function timer_stop() {
-                $mtime = microtime();
-                $mtime = explode(' ', $mtime);
-                $time_end = $mtime[1] + $mtime[0];
+                $mtime      = explode( ' ', microtime() );
+                $time_end   = $mtime[1] + $mtime[0];
                 $time_total = $time_end - $this->time_start;
                 return $time_total;
         }
@@ -1266 +1435 @@
          * @param string $error_code (optional) A Computer readable string to identify the error.
          * @return false|void
          */
-        function bail($message, $error_code = '500') {
+        function bail( $message, $error_code = '500' ) {
                 if ( !$this->show_errors ) {
-                        if ( class_exists('WP_Error') )
+                        if ( class_exists( 'WP_Error' ) )
                                 $this->error = new WP_Error($error_code, $message);
                         else
                                 $this->error = $message;
@@ -1282 +1451 @@
          *
          * @since 2.5.0
          * @uses $wp_version
+         * @uses $required_mysql_version
          *
          * @return WP_Error
          */
@@ -1289 +1459 @@
                 global $wp_version, $required_mysql_version;
                 // Make sure the server has the required MySQL version
                 if ( version_compare($this->db_version(), $required_mysql_version, '<') )
-                        return new WP_Error('database_version',sprintf(__('<strong>ERROR</strong>: WordPress %1$s requires MySQL %2$s or higher'), $wp_version, $required_mysql_version));
+                        return new WP_Error('database_version', sprintf( __( '<strong>ERROR</strong>: WordPress %1$s requires MySQL %2$s or higher' ), $wp_version, $required_mysql_version ));
         }
 
         /**
@@ -1306 +1476 @@
         }
 
         /**
-         * Generic function to determine if a database supports a particular feature
+         * has capability
+         *
+         * Determine if a database supports a particular feature
+         *
+         * @since  2.7
+         * @see    db_version()
+         *
          * @param string $db_cap the feature
          * @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.
          * @return bool
@@ -1318 +1494 @@
                 case 'collation' :    // @since 2.5.0
                 case 'group_concat' : // @since 2.7
                 case 'subqueries' :   // @since 2.7
-                        return version_compare($version, '4.1', '>=');
+                        return version_compare( $version, '4.1', '>=' );
                         break;
                 endswitch;
 
@@ -1336 +1512 @@
          * @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;
+                                continue; # filter out function calls of this object's class
+
                         $function = $call['function'];
+
                         if ( isset( $call['class'] ) )
                                 $function = $call['class'] . "->$function";
+
                         $caller[] = $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.
+         * get database version number
+         *
+         * 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() {
-                return preg_replace('/[^0-9.].*/', '', mysql_get_server_info( $this->dbh ));
+                return preg_replace( '/[^0-9.].*/', '', mysql_get_server_info( $this->dbh ) );
         }
 }
 
@@ -1371 +1564 @@
          */
         $wpdb = new wpdb(DB_USER, DB_PASSWORD, DB_NAME, DB_HOST);
 }
-?>
+?>
+ No newline at end of file