diff options
author | donncha <donncha@7be80a69-a1ef-0310-a953-fb0f7c49ff36> | 2008-06-24 17:00:10 +0000 |
---|---|---|
committer | donncha <donncha@7be80a69-a1ef-0310-a953-fb0f7c49ff36> | 2008-06-24 17:00:10 +0000 |
commit | 631c9bb4d60d242432052f56c00768392f42a392 (patch) | |
tree | 50d41b0248d5c5fb156c6d52020675208b77a3e6 /wp-includes/wp-db.php | |
parent | a1fbe4e0694a66d7351e2f6280ab84568681e8e0 (diff) | |
download | wordpress-mu-631c9bb4d60d242432052f56c00768392f42a392.tar.gz wordpress-mu-631c9bb4d60d242432052f56c00768392f42a392.tar.xz wordpress-mu-631c9bb4d60d242432052f56c00768392f42a392.zip |
WP Merge to revision 8180
git-svn-id: http://svn.automattic.com/wordpress-mu/trunk@1336 7be80a69-a1ef-0310-a953-fb0f7c49ff36
Diffstat (limited to 'wp-includes/wp-db.php')
-rw-r--r-- | wp-includes/wp-db.php | 551 |
1 files changed, 466 insertions, 85 deletions
diff --git a/wp-includes/wp-db.php b/wp-includes/wp-db.php index 00c7e81..74e38ea 100644 --- a/wp-includes/wp-db.php +++ b/wp-includes/wp-db.php @@ -1,66 +1,298 @@ <?php -// WordPress DB Class - -// ORIGINAL CODE FROM: -// Justin Vincent (justin@visunet.ie) -// http://php.justinvincent.com - +/** + * WordPress DB Class + * + * Original code from {@link http://php.justinvincent.com Justin Vincent (justin@visunet.ie)} + * + * @package WordPress + * @subpackage Database + * @since 0.71 + */ + +/** + * @since 0.71 + */ define('EZSQL_VERSION', 'WP1.25'); + +/** + * @since 0.71 + */ define('OBJECT', 'OBJECT', true); + +/** + * @since {@internal Version Unknown}} + */ define('OBJECT_K', 'OBJECT_K', false); + +/** + * @since 0.71 + */ define('ARRAY_A', 'ARRAY_A', false); -define('ARRAY_N', 'ARRAY_N', false); -if (!defined('SAVEQUERIES')) - define('SAVEQUERIES', false); +/** + * @since 0.71 + */ +define('ARRAY_N', 'ARRAY_N', false); +/** + * WordPress Database Access Abstraction Object + * + * It is possible to replace this class with your own + * by setting the $wpdb global variable in wp-content/wpdb.php + * file with your class. You can name it wpdb also, since + * this file will not be included, if the other file is + * available. + * + * @link http://codex.wordpress.org/Function_Reference/wpdb_Class + * + * @package WordPress + * @subpackage Database + * @since 0.71 + * @final + */ class wpdb { + /** + * Whether to show SQL/DB errors + * + * @since 0.71 + * @access private + * @var bool + */ var $show_errors = false; + + /** + * Whether to suppress errors during the DB bootstrapping. + * + * @access private + * @since {@internal Version Unknown}} + * @var bool + */ var $suppress_errors = false; + + /** + * The last error during query. + * + * @since {@internal Version Unknown}} + * @var string + */ var $last_error = ''; + + /** + * Amount of queries made + * + * @since 1.2.0 + * @access private + * @var int + */ var $num_queries = 0; + + /** + * Saved result of the last query made + * + * @since 1.2.0 + * @access private + * @var array + */ var $last_query; + + /** + * Saved info on the table column + * + * @since 1.2.0 + * @access private + * @var array + */ var $col_info; + + /** + * Saved queries that were executed + * + * @since 1.5.0 + * @access private + * @var array + */ var $queries; + + /** + * WordPress table prefix + * + * You can set this to have multiple WordPress installations + * in a single database. The second reason is for possible + * security precautions. + * + * @since 0.71 + * @access private + * @var string + */ var $prefix = ''; + + /** + * Whether the database queries are ready to start executing. + * + * @since 2.5.0 + * @access private + * @var bool + */ var $ready = false; var $blogid = 0; var $siteid = 0; - - // Global tables var $blogs; var $signups; var $site; var $sitemeta; - var $users; var $usermeta; var $sitecategories; var $global_tables = array('blogs', 'signups', 'site', 'sitemeta', 'users', 'usermeta', 'sitecategories', 'registration_log', 'blog_versions'); - // Blog tables + /** + * WordPress Posts table + * + * @since 1.5.0 + * @access public + * @var string + */ var $posts; + + /** + * WordPress Users table + * + * @since 1.5.0 + * @access public + * @var string + */ + var $users; + + /** + * WordPress Categories table + * + * @since 1.5.0 + * @access public + * @var string + */ var $categories; + + /** + * WordPress Post to Category table + * + * @since 1.5.0 + * @access public + * @var string + */ var $post2cat; + + /** + * WordPress Comments table + * + * @since 1.5.0 + * @access public + * @var string + */ var $comments; + + /** + * WordPress Links table + * + * @since 1.5.0 + * @access public + * @var string + */ var $links; + + /** + * WordPress Options table + * + * @since 1.5.0 + * @access public + * @var string + */ var $options; + + /** + * WordPress Post Metadata table + * + * @since {@internal Version Unknown}} + * @access public + * @var string + */ var $postmeta; + + /** + * WordPress User Metadata table + * + * @since 2.3.0 + * @access public + * @var string + */ + var $usermeta; + + /** + * WordPress Terms table + * + * @since 2.3.0 + * @access public + * @var string + */ var $terms; + + /** + * WordPress Term Taxonomy table + * + * @since 2.3.0 + * @access public + * @var string + */ var $term_taxonomy; + + /** + * WordPress Term Relationships table + * + * @since 2.3.0 + * @access public + * @var string + */ var $term_relationships; + + /** + * List of WordPress tables + * + * @since {@internal Version Unknown}} + * @access private + * @var array + */ var $blog_tables = array('posts', 'categories', 'post2cat', 'comments', 'links', 'link2cat', 'options', 'postmeta', 'terms', 'term_taxonomy', 'term_relationships'); + /** + * Database table columns charset + * + * @since 2.2.0 + * @access public + * @var string + */ var $charset; + + /** + * Database table columns collate + * + * @since 2.2.0 + * @access public + * @var string + */ var $collate; /** * Connects to the database server and selects a database - * @param string $dbuser - * @param string $dbpassword - * @param string $dbname - * @param string $dbhost + * + * PHP4 compatibility layer for calling the PHP5 constructor. + * + * @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 */ function wpdb($dbuser, $dbpassword, $dbname, $dbhost) { if( defined( "WP_USE_MULTIPLE_DB" ) && CONSTANT( "WP_USE_MULTIPLE_DB" ) == true ) @@ -68,6 +300,20 @@ class wpdb { return $this->__construct($dbuser, $dbpassword, $dbname, $dbhost); } + /** + * Connects to the database server and selects a database + * + * PHP5 style constructor for compatibility with PHP5. Does + * the actual setting up of the class properties and connection + * to the database. + * + * @since 2.0.8 + * + * @param string $dbuser MySQL database user + * @param string $dbpassword MySQL database password + * @param string $dbname MySQL database name + * @param string $dbhost MySQL database host + */ function __construct($dbuser, $dbpassword, $dbname, $dbhost) { register_shutdown_function(array(&$this, "__destruct")); @@ -89,16 +335,16 @@ class wpdb { $this->dbh = @mysql_connect($dbhost, $dbuser, $dbpassword, true); if (!$this->dbh) { - $this->bail(" + $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>$dbhost</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> -"); +"/*/WP_I18N_DB_CONN_ERROR*/, $dbhost)); return; } @@ -120,14 +366,32 @@ class wpdb { $this->select($dbname, $this->dbh); } + /** + * PHP5 style destructor and will run when database object is destroyed. + * + * @since 2.0.8 + * + * @return bool Always true + */ function __destruct() { return true; } + /** + * Sets the table prefix for the WordPress tables. + * + * Also allows for the CUSTOM_USER_TABLE and CUSTOM_USER_META_TABLE to + * override the WordPress users and usersmeta tables. + * + * @since 2.5.0 + * + * @param string $prefix Alphanumeric name for the new prefix. + * @return string Old prefix + */ function set_prefix($prefix) { if ( preg_match('|[^a-z0-9_]|i', $prefix) ) - return new WP_Error('invalid_db_prefix', 'Invalid database prefix'); // No gettext here + return new WP_Error('invalid_db_prefix', /*WP_I18N_DB_BAD_PREFIX*/'Invalid database prefix'/*/WP_I18N_DB_BAD_PREFIX*/); $old_prefix = $this->base_prefix; $this->base_prefix = $prefix; @@ -168,21 +432,28 @@ class wpdb { /** - * Selects a database using the current class's $this->dbh - * @param string $db name + * Selects a database using the current database connection. + * + * The database name will be changed based on the current database + * connection. On failure, the execution will bail and display an DB error. + * + * @since 0.71 + * + * @param string $db MySQL database name + * @return null Always null. */ function select($db, &$dbh) { if (!@mysql_select_db($db, $dbh)) { $this->ready = false; - $this->bail(" + $this->bail(sprintf(/*WP_I18N_DB_SELECT_DB*/' <h1>Can’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>$db</code> database.</p> +<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>".DB_USER."</code> have permission to use the <code>$db</code> database?</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 username_wordpress. 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>"); +<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, DB_USER)); return; } } @@ -190,6 +461,8 @@ class wpdb { /** * Escapes content for insertion into the database, for security * + * @since 0.71 + * * @param string $string * @return string query safe string */ @@ -206,6 +479,9 @@ class wpdb { /** * Escapes content by reference for insertion into the database, for security + * + * @since 2.3.0 + * * @param string $s */ function escape_by_ref(&$s) { @@ -213,10 +489,17 @@ class wpdb { } /** - * Prepares a SQL query for safe use, using sprintf() syntax + * Prepares a SQL query for safe use, using sprintf() syntax. + * + * @link http://php.net/sprintf See for syntax to use for query string. + * @since 2.3.0 + * + * @param null|string $args If string, first parameter must be query statement + * @param mixed $args,... If additional parameters, they will be set inserted into the query. + * @return null|string Sanitized query string */ - function prepare($args=NULL) { - if ( NULL === $args ) + function prepare($args=null) { + if ( is_null( $args ) ) return; $args = func_get_args(); $query = array_shift($args); @@ -227,22 +510,28 @@ class wpdb { return @vsprintf($query, $args); } - // ================================================================== - // Print SQL/DB error. - + /** + * Print SQL/DB error. + * + * @since 0.71 + * @global array $EZSQL_ERROR Stores error information of query and error string + * + * @param string $str The error to display + * @return bool False if the showing of errors is disabled. + */ function print_error($str = '') { global $EZSQL_ERROR; if (!$str) $str = mysql_error($this->dbh); - $EZSQL_ERROR[] = - array ('query' => $this->last_query, 'error_str' => $str); + $EZSQL_ERROR[] = array ('query' => $this->last_query, 'error_str' => $str); if ( $this->suppress_errors ) return false; - $error_str = "WordPress database error $str for query $this->last_query"; if ( $caller = $this->get_caller() ) - $error_str .= " made by $caller"; + $error_str = sprintf(/*WP_I18N_DB_QUERY_ERROR_FULL*/'WordPress database error %1$s for query %2$s made by %3$s'/*/WP_I18N_DB_QUERY_ERROR_FULL*/, $str, $this->last_query, $caller); + 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') ) @@ -267,30 +556,55 @@ class wpdb { die( $msg ); } - // ================================================================== - // Turn error handling on or off.. - + /** + * Enables showing of database errors. + * + * This function should be used only to enable showing of errors. + * wpdb::hide_errors() should be used instead for hiding of errors. However, + * this function can be used to enable and disable showing of database + * errors. + * + * @since 0.71 + * + * @param bool $show Whether to show or hide errors + * @return bool Old value for showing errors. + */ function show_errors( $show = true ) { $errors = $this->show_errors; $this->show_errors = $show; return $errors; } + /** + * Disables showing of database errors. + * + * @since 0.71 + * + * @return bool Whether showing of errors was active or not + */ function hide_errors() { $show = $this->show_errors; $this->show_errors = false; return $show; } + /** + * Whether to suppress database errors. + * + * @param unknown_type $suppress + * @return unknown + */ function suppress_errors( $suppress = true ) { $errors = $this->suppress_errors; $this->suppress_errors = $suppress; return $errors; } - // ================================================================== - // Kill cached query results - + /** + * Kill cached query results. + * + * @since 0.71 + */ function flush() { $this->last_result = array(); $this->col_info = null; @@ -333,9 +647,16 @@ class wpdb { $this->select( $details[ 'db_name' ], $this->$dbhname ); } - // ================================================================== - // Basic Query - see docs for more detail - + /** + * Perform a MySQL database query, using current database connection. + * + * More information can be found on the codex page. + * + * @since 0.71 + * + * @param string $query + * @return unknown + */ function query($query) { if ( ! $this->ready ) return false; @@ -356,7 +677,7 @@ class wpdb { $this->last_query = $query; // Perform the query via std mysql_query function.. - if (SAVEQUERIES) + if ( defined('SAVEQUERIES') && SAVEQUERIES ) $this->timer_start(); // use $this->dbh for read ops, and $this->dbhwrite for write ops @@ -387,7 +708,7 @@ class wpdb { $this->result = @mysql_query($query, $dbh); ++$this->num_queries; - if (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.. @@ -431,10 +752,13 @@ class wpdb { } /** - * Insert an array of data into a table + * Insert an array of data into a table. + * + * @since 2.5.0 + * * @param string $table WARNING: not sanitized! - * @param array $data should not already be SQL-escaped - * @return mixed results of $this->query() + * @param array $data Should not already be SQL-escaped + * @return mixed Results of $this->query() */ function insert($table, $data) { $data = add_magic_quotes($data); @@ -443,11 +767,14 @@ class wpdb { } /** - * Update a row in the table with an array of data + * Update a row in the table with an array of data. + * + * @since 2.5.0 + * * @param string $table WARNING: not sanitized! - * @param array $data should not already be SQL-escaped - * @param array $where a named array of WHERE column => value relationships. Multiple member pairs will be joined with ANDs. WARNING: the column names are not currently sanitized! - * @return mixed results of $this->query() + * @param array $data Should not already be SQL-escaped + * @param array $where A named array of WHERE column => value relationships. Multiple member pairs will be joined with ANDs. WARNING: the column names are not currently sanitized! + * @return mixed Results of $this->query() */ function update($table, $data, $where){ $data = add_magic_quotes($data); @@ -464,11 +791,21 @@ class wpdb { } /** - * Get one variable from the database - * @param string $query (can be null as well, for caching, see codex) - * @param int $x = 0 row num to return - * @param int $y = 0 col num to return - * @return mixed results + * Retrieve one variable from the database. + * + * This combines the functionality of wpdb::get_row() and wpdb::get_col(), + * so both the column and row can be picked. + * + * It is possible to use this function without executing more queries. If + * you already made a query, you can set the $query to 'null' value and just + * retrieve either the column and row of the last query result. + * + * @since 0.71 + * + * @param string $query Can be null as well, for caching + * @param int $x Column num to return + * @param int $y Row num to return + * @return mixed Database query results */ function get_var($query=null, $x = 0, $y = 0) { $this->func_call = "\$db->get_var(\"$query\",$x,$y)"; @@ -485,11 +822,14 @@ class wpdb { } /** - * Get one row from the database - * @param string $query + * Retrieve one row from the database. + * + * @since 0.71 + * + * @param string $query SQL query * @param string $output ARRAY_A | ARRAY_N | OBJECT - * @param int $y row num to return - * @return mixed results + * @param int $y Row num to return + * @return mixed Database query results */ function get_row($query = null, $output = OBJECT, $y = 0) { $this->func_call = "\$db->get_row(\"$query\",$output,$y)"; @@ -508,15 +848,18 @@ class wpdb { } elseif ( $output == ARRAY_N ) { return $this->last_result[$y] ? array_values(get_object_vars($this->last_result[$y])) : null; } else { - $this->print_error(" \$db->get_row(string query, output type, int offset) -- Output type must be one of: OBJECT, ARRAY_A, ARRAY_N"); + $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*/); } } /** - * Gets one column from the database - * @param string $query (can be null as well, for caching, see codex) - * @param int $x col num to return - * @return array results + * Retrieve one column from the database. + * + * @since 0.71 + * + * @param string $query Can be null as well, for caching + * @param int $x Col num to return. Starts from 0. + * @return array Column results */ function get_col($query = null , $x = 0) { if ( $query ) @@ -531,10 +874,13 @@ class wpdb { } /** - * Return an entire result set from the database - * @param string $query (can also be null to pull from the cache) + * Retrieve an entire result set from the database. + * + * @since 0.71 + * + * @param string|null $query Can also be null to pull from the cache * @param string $output ARRAY_A | ARRAY_N | OBJECT_K | OBJECT - * @return mixed results + * @return mixed Database query results */ function get_results($query = null, $output = OBJECT) { $this->func_call = "\$db->get_results(\"$query\", $output)"; @@ -576,10 +922,13 @@ class wpdb { } /** - * Grabs column metadata from the last query + * Retrieve column metadata from the last query. + * + * @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 - * @return mixed results + * @return mixed Column Results */ function get_col_info($info_type = 'name', $col_offset = -1) { if ( $this->col_info ) { @@ -597,7 +946,11 @@ class wpdb { } /** - * Starts the timer, for debugging purposes + * Starts the timer, for debugging purposes. + * + * @since 1.5.0 + * + * @return bool Always returns true */ function timer_start() { $mtime = microtime(); @@ -607,8 +960,11 @@ class wpdb { } /** - * Stops the debugging timer - * @return int total time spent on the query, in milliseconds + * Stops the debugging timer. + * + * @since 1.5.0 + * + * @return int Total time spent on the query, in milliseconds */ function timer_stop() { $mtime = microtime(); @@ -620,9 +976,13 @@ class wpdb { /** * Wraps fatal errors in a nice header and footer and dies. + * + * @since 1.5.0 + * * @param string $message + * @return unknown */ - function bail($message) { // Just wraps errors in a nice header and footer + function bail($message) { if ( !$this->show_errors ) { if ( class_exists('WP_Error') ) $this->error = new WP_Error('500', $message); @@ -634,8 +994,12 @@ class wpdb { } /** - * Checks wether of not the database version is high enough to support the features WordPress uses - * @global $wp_version + * Whether or not MySQL database is minimal required version. + * + * @since 2.5.0 + * @uses $wp_version + * + * @return WP_Error */ function check_database_version() { @@ -647,8 +1011,13 @@ class wpdb { } /** - * This function is called when WordPress is generating the table schema to determine wether or not the current database - * supports or needs the collation statements. + * Whether of not the database version supports collation. + * + * Called when WordPress is generating the table scheme. + * + * @since 2.5.0 + * + * @return bool True if collation is supported, false if version does not */ function supports_collation() { @@ -656,8 +1025,14 @@ class wpdb { } /** - * Get the name of the function that called wpdb. - * @return string the name of the calling function + * Retrieve the name of the function that called wpdb. + * + * Requires PHP 4.3 and searches up the list of functions until it reaches + * the one that would most logically had called this method. + * + * @since 2.5.0 + * + * @return string The name of the calling function */ function get_caller() { // requires PHP 4.3+ @@ -685,6 +1060,12 @@ class wpdb { } -if ( ! isset($wpdb) ) +if ( ! isset($wpdb) ) { + /** + * WordPress Database Object, if it isn't set already in wp-content/wpdb.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); +} ?> |