Index: wp-includes/wp-db.php
===================================================================
--- wp-includes/wp-db.php (revision 10907)
+++ wp-includes/wp-db.php (working copy)
@@ -373,12 +373,12 @@
* 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.
+ * override the WordPress users and usersmeta tables that would otherwise be determined by the $prefix.
*
* @since 2.5.0
*
* @param string $prefix Alphanumeric name for the new prefix.
- * @return string Old prefix
+ * @return string|WP_Error Old prefix or WP_Error on error
*/
function set_prefix($prefix) {
@@ -488,21 +488,34 @@
}
/**
- * Prepares a SQL query for safe use, using sprintf() syntax.
+ * Prepares a SQL query for safe execution. Uses sprintf()-like syntax.
*
- * @link http://php.net/sprintf See for syntax to use for query string.
+ * 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.
+ *
+ * May be called like {@link http://php.net/sprintf sprintf()} or like {@link http://php.net/vsprintf vsprintf()}.
+ *
+ * Both %d and %s should be left unquoted in the query string.
+ *
+ *
+ * wpdb::prepare( "SELECT * FROM `table` WHERE `column` = %s AND `field` = %d", "foo", 1337 )
+ *
+ *
+ * @link http://php.net/sprintf Description of syntax.
* @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.
+ * @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,... 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
*/
- function prepare($args=null) {
- if ( is_null( $args ) )
+ function prepare($query = null) { // ( $query, *$args )
+ if ( is_null( $query ) )
return;
$args = func_get_args();
- $query = array_shift($args);
- // If args were passed as an array, move them up
+ 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
@@ -623,7 +636,7 @@
* @since 0.71
*
* @param string $query
- * @return unknown
+ * @return int|false Number of rows affected/selected or false on error
*/
function query($query) {
if ( ! $this->ready )
@@ -693,14 +706,19 @@
}
/**
- * Insert an array of data into a table.
+ * Insert a row into a table.
*
+ *
+ * wpdb::insert( 'table', array( 'column' => 'foo', 'field' => 1337 ), array( '%s', '%d' ) )
+ *
+ *
* @since 2.5.0
+ * @see wpdb::prepare()
*
* @param string $table table name
- * @param array $data Should not already be SQL-escaped
- * @param array|string $format The format of the field values.
- * @return mixed Results of $this->query()
+ * @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.
+ * @return int|false The number of rows inserted, or false on error.
*/
function insert($table, $data, $format = null) {
global $db_field_types;
@@ -721,17 +739,23 @@
return $this->query( $this->prepare( $sql, $data) );
}
+
/**
- * Update a row in the table with an array of data.
+ * Update a row in the table
*
+ *
+ * wpdb::update( 'table', array( 'column' => 'foo', 'field' => 1337 ), array( 'ID' => 1 ), array( '%s', '%d' ), array( '%d' ) )
+ *
+ *
* @since 2.5.0
+ * @see wpdb::prepare()
*
* @param string $table table name
- * @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.
- * @param array|string $format The format of the field values.
- * @param array|string $where_format The format of the where field values.
- * @return mixed Results of $this->query()
+ * @param array $data Data to update (in column => value pairs). Both $data columns and $data values should be "raw" (neither should be SQL escaped).
+ * @param array $where A named array of WHERE clauses (in column => value pairs). Multiple clauses will be joined with ANDs. Both $where columns and $where values should be "raw".
+ * @param array|string $format (optional) An array of formats to be mapped to each of the values in $data. If string, that format will be used for all of the values in $data. A format is one of '%d', '%s' (decimal number, string). If omitted, all values in $data will be treated as strings.
+ * @param array|string $format_where (optional) An array of formats to be mapped to each of the values in $where. If string, that format will be used for all of the items in $where. A format is one of '%d', '%s' (decimal number, string). If omitted, all values in $where will be treated as strings.
+ * @return int|false The number of rows updated, or false on error.
*/
function update($table, $data, $where, $format = null, $where_format = null) {
global $db_field_types;
@@ -769,19 +793,16 @@
/**
* 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.
+ * Executes a SQL query and returns the value from the SQL result.
+ * If the SQL result contains more than one column and/or more than one row, this function returns the value in the column and row specified.
+ * If $query is null, this function returns the value in the specified column and row from the previous SQL result.
*
- * 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
+ * @param string|null $query SQL query. If 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
*/
function get_var($query=null, $x = 0, $y = 0) {
$this->func_call = "\$db->get_var(\"$query\",$x,$y)";
@@ -800,12 +821,14 @@
/**
* Retrieve one row from the database.
*
+ * Executes a SQL query and returns the row from the SQL result.
+ *
* @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 Database query results
+ * @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
*/
function get_row($query = null, $output = OBJECT, $y = 0) {
$this->func_call = "\$db->get_row(\"$query\",$output,$y)";
@@ -831,11 +854,15 @@
/**
* Retrieve one column from the database.
*
+ * Executes a SQL query and returns the column from the SQL result.
+ * If the SQL result contains more than one column, this function returns the column specified.
+ * If $query is null, this function returns the specified column from the previous SQL result.
+ *
* @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
+ * @param string|null $query SQL query. If null, use the result from the previous query.
+ * @param int $x 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) {
if ( $query )
@@ -850,12 +877,14 @@
}
/**
- * Retrieve an entire result set from the database.
+ * Retrieve an entire SQL result set from the database (i.e., many rows)
*
+ * Executes a SQL query and returns the entire SQL result.
+ *
* @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
+ * @param string $query SQL query.
+ * @param string $output (optional) ane of ARRAY_A | ARRAY_N | OBJECT | OBJECT_K constants. With one of the first three, return an array of rows indexed from 0 by SQL result row number. Each row is an associative array (column => value, ...), a numerically indexed array (0 => value, ...), or an object. ( ->column = value ), respectively. With OBJECT_K, return an associative array of row objects keyed by the value of each row's first column's value. Duplicate keys are discarded.
* @return mixed Database query results
*/
function get_results($query = null, $output = OBJECT) {
@@ -926,7 +955,7 @@
*
* @since 1.5.0
*
- * @return bool Always returns true
+ * @return true
*/
function timer_start() {
$mtime = microtime();
@@ -951,12 +980,14 @@
}
/**
- * Wraps fatal errors in a nice header and footer and dies.
+ * Wraps errors in a nice header and footer and dies.
*
+ * Will not die if wpdb::$show_errors is true
+ *
* @since 1.5.0
*
* @param string $message
- * @return unknown
+ * @return false|void
*/
function bail($message) {
if ( !$this->show_errors ) {
@@ -970,7 +1001,7 @@
}
/**
- * Whether or not MySQL database is minimal required version.
+ * Whether or not MySQL database is at least the required minimum version.
*
* @since 2.5.0
* @uses $wp_version
@@ -986,7 +1017,7 @@
}
/**
- * Whether of not the database version supports collation.
+ * Whether of not the database supports collation.
*
* Called when WordPress is generating the table scheme.
*
@@ -1002,7 +1033,7 @@
/**
* Generic function to determine if a database supports a particular feature
* @param string $db_cap the feature
- * @param false|string|resource $dbh_or_table the databaese (the current database, the database housing the specified table, or the database of the mysql resource)
+ * @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
*/
function has_cap( $db_cap ) {
@@ -1053,6 +1084,7 @@
/**
* 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.
* @return false|string false on failure, version number on success
*/
function db_version() {