Upstream/WordPress
1
0
Fork 0
mirror of https://github.com/WordPress/WordPress.git synced 2024-11-12 13:44:21 +01:00
Code Issues Projects Releases Wiki Activity

phpdoc updates for wpdb. Props mdawaffe. fixes #9506

Browse Source 
git-svn-id: http://svn.automattic.com/wordpress/trunk@10911 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
ryan 2009-04-10 21:57:40 +00:00
parent 658d22d054
commit 7c460ad4d3
1 changed files with 79 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

126
wp-includes/wp-db.php
View File

@ -387,12 +387,12 @@ class wpdb {
* Sets the table prefix for the WordPress tables. * Sets the table prefix for the WordPress tables.
* *
* Also allows for the CUSTOM_USER_TABLE and CUSTOM_USER_META_TABLE to * 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 * @since 2.5.0
* *
* @param string $prefix Alphanumeric name for the new prefix. * @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) { function set_prefix($prefix) {
@ -502,21 +502,34 @@ class wpdb {
} }
/** /**
* 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.
*
* <code>
* wpdb::prepare( "SELECT * FROM `table` WHERE `column` = %s AND `field` = %d", "foo", 1337 )
* </code>
*
* @link http://php.net/sprintf Description of syntax.
* @since 2.3.0 * @since 2.3.0
* *
* @param null|string $args If string, first parameter must be query statement * @param string $query Query statement with sprintf()-like placeholders
* @param mixed $args,... If additional parameters, they will be set inserted into the query. * @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 * @return null|string Sanitized query string
*/ */
function prepare($args=null) { function prepare($query = null) { // ( $query, *$args )
if ( is_null( $args ) ) if ( is_null( $query ) )
return; return;
$args = func_get_args(); $args = func_get_args();
$query = array_shift($args); array_shift($args);
// If args were passed as an array, move them up // If args were passed as an array (as in vsprintf), move them up
if ( isset($args[0]) && is_array($args[0]) ) if ( isset($args[0]) && is_array($args[0]) )
$args = $args[0]; $args = $args[0];
$query = str_replace("'%s'", '%s', $query); // in case someone mistakenly already singlequoted it $query = str_replace("'%s'", '%s', $query); // in case someone mistakenly already singlequoted it
@ -637,7 +650,7 @@ class wpdb {
* @since 0.71 * @since 0.71
* *
* @param string $query * @param string $query
* @return unknown * @return int|false Number of rows affected/selected or false on error
*/ */
function query($query) { function query($query) {
if ( ! $this->ready ) if ( ! $this->ready )
@ -707,14 +720,19 @@ class wpdb {
} }
/** /**
* Insert an array of data into a table. * Insert a row into a table.
*
* <code>
* wpdb::insert( 'table', array( 'column' => 'foo', 'field' => 1337 ), array( '%s', '%d' ) )
* </code>
* *
* @since 2.5.0 * @since 2.5.0
* @see wpdb::prepare()
* *
* @param string $table table name * @param string $table table name
* @param array $data Should not already be SQL-escaped * @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 The format of the field values. * @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 mixed Results of $this->query() * @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; $formats = $format = (array) $format;
@ -733,17 +751,23 @@ class wpdb {
return $this->query( $this->prepare( $sql, $data) ); return $this->query( $this->prepare( $sql, $data) );
} }
/** /**
* Update a row in the table with an array of data. * Update a row in the table
*
* <code>
* wpdb::update( 'table', array( 'column' => 'foo', 'field' => 1337 ), array( 'ID' => 1 ), array( '%s', '%d' ), array( '%d' ) )
* </code>
* *
* @since 2.5.0 * @since 2.5.0
* @see wpdb::prepare()
* *
* @param string $table table name * @param string $table table name
* @param array $data Should not already be SQL-escaped * @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 column => value relationships. Multiple member pairs will be joined with ANDs. * @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 The format of the field values. * @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 $where_format The format of the where field values. * @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 mixed Results of $this->query() * @return int|false The number of rows updated, or false on error.
*/ */
function update($table, $data, $where, $format = null, $where_format = null) { function update($table, $data, $where, $format = null, $where_format = null) {
if ( !is_array( $where ) ) if ( !is_array( $where ) )
@ -779,19 +803,16 @@ class wpdb {
/** /**
* Retrieve one variable from the database. * Retrieve one variable from the database.
* *
* This combines the functionality of wpdb::get_row() and wpdb::get_col(), * Executes a SQL query and returns the value from the SQL result.
* so both the column and row can be picked. * 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 * @since 0.71
* *
* @param string $query Can be null as well, for caching * @param string|null $query SQL query. If null, use the result from the previous query.
* @param int $x Column num to return * @param int $x (optional) Column of value to return. Indexed from 0.
* @param int $y Row num to return * @param int $y (optional) Row of value to return. Indexed from 0.
* @return mixed Database query results * @return string Database query result
*/ */
function get_var($query=null, $x = 0, $y = 0) { function get_var($query=null, $x = 0, $y = 0) {
$this->func_call = "\$db->get_var(\"$query\",$x,$y)"; $this->func_call = "\$db->get_var(\"$query\",$x,$y)";
@ -810,12 +831,14 @@ class wpdb {
/** /**
* Retrieve one row from the database. * Retrieve one row from the database.
* *
* Executes a SQL query and returns the row from the SQL result.
*
* @since 0.71 * @since 0.71
* *
* @param string $query SQL query * @param string|null $query SQL query.
* @param string $output ARRAY_A | ARRAY_N | OBJECT * @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 Row num to return * @param int $y (optional) Row to return. Indexed from 0.
* @return mixed Database query results * @return mixed Database query result in format specifed by $output
*/ */
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)"; $this->func_call = "\$db->get_row(\"$query\",$output,$y)";
@ -841,11 +864,15 @@ class wpdb {
/** /**
* Retrieve one column from the database. * 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 * @since 0.71
* *
* @param string $query Can be null as well, for caching * @param string|null $query SQL query. If null, use the result from the previous query.
* @param int $x Col num to return. Starts from 0. * @param int $x Column to return. Indexed from 0.
* @return array Column results * @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 ) if ( $query )
@ -860,12 +887,14 @@ class wpdb {
} }
/** /**
* 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 * @since 0.71
* *
* @param string|null $query Can also be null to pull from the cache * @param string $query SQL query.
* @param string $output ARRAY_A | ARRAY_N | OBJECT_K | OBJECT * @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 * @return mixed Database query results
*/ */
function get_results($query = null, $output = OBJECT) { function get_results($query = null, $output = OBJECT) {
@ -936,7 +965,7 @@ class wpdb {
* *
* @since 1.5.0 * @since 1.5.0
* *
* @return bool Always returns true * @return true
*/ */
function timer_start() { function timer_start() {
$mtime = microtime(); $mtime = microtime();
@ -961,12 +990,14 @@ class wpdb {
} }
/** /**
* 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 * @since 1.5.0
* *
* @param string $message * @param string $message
* @return unknown * @return false|void
*/ */
function bail($message) { function bail($message) {
if ( !$this->show_errors ) { if ( !$this->show_errors ) {
@ -980,7 +1011,7 @@ class wpdb {
} }
/** /**
* 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 * @since 2.5.0
* @uses $wp_version * @uses $wp_version
@ -996,7 +1027,7 @@ class wpdb {
} }
/** /**
* Whether of not the database version supports collation. * Whether of not the database supports collation.
* *
* Called when WordPress is generating the table scheme. * Called when WordPress is generating the table scheme.
* *
@ -1012,7 +1043,7 @@ class wpdb {
/** /**
* Generic function to determine if a database supports a particular feature * Generic function to determine if a database supports a particular feature
* @param string $db_cap the 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 * @return bool
*/ */
function has_cap( $db_cap ) { function has_cap( $db_cap ) {
@ -1063,6 +1094,7 @@ class wpdb {
/** /**
* The database version number * 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 * @return false|string false on failure, version number on success
*/ */
function db_version() { function db_version() {