Upstream/WordPress
1
0
Fork 0
mirror of https://github.com/WordPress/WordPress.git synced 2024-06-23 13:24:57 +02:00
Code Issues Projects Releases Wiki Activity

Docs: Further update inline documentation for the wpdb class per the documentation standards.

Browse Source 
Restore some previous edits from [46696], [47060], [47122], [47230] that were accidentally reverted in [47740].

See #49572.
Built from https://develop.svn.wordpress.org/trunk@47749


git-svn-id: http://core.svn.wordpress.org/trunk@47525 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
Sergey Biryukov 2020-05-03 11:45:06 +00:00
parent f89f744fb2
commit 72ef4ae81a
2 changed files with 214 additions and 179 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
wp-includes/version.php
View File

@ -13,7 +13,7 @@
*
* @global string $wp_version
*/
$wp_version = '5.5-alpha-47748';
$wp_version = '5.5-alpha-47749';
/**
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.

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

@ -37,10 +37,15 @@ define( 'ARRAY_A', 'ARRAY_A' );
define( 'ARRAY_N', 'ARRAY_N' );
/**
* WordPress database access abstraction class
* WordPress database access abstraction class.
*
* This class is used to interact with a database without needing to use raw SQL statements. By default, WordPress
* uses this class to instantiate the global $wpdb object, providing access to the WordPress database.
* This class is used to interact with a database without needing to use raw SQL statements.
* By default, WordPress uses this class to instantiate the global $wpdb object, providing
* access to the WordPress database.
*
* It is possible to replace this class with your own by setting the $wpdb global variable
* in wp-content/db.php file to your class. The wpdb class will still be included, so you can
* extend it or simply use your own.
*
* @link https://developer.wordpress.org/reference/classes/wpdb/
*
@ -67,7 +72,7 @@ class wpdb {
var $suppress_errors = false;
/**
* The last error encountered during the last query.
* The error encountered during the last query.
*
* @since 2.5.0
* @var string
@ -187,7 +192,7 @@ class wpdb {
*
* @type string $0 The query's SQL.
* @type float $1 Total time spent on the query, in seconds.
* @type string $2 Comma separated list of the calling functions.
* @type string $2 Comma-separated list of the calling functions.
* @type float $3 Unix timestamp of the time at the start of the query.
* @type array $4 Custom query data.
* }
@ -270,7 +275,7 @@ class wpdb {
/**
* List of deprecated WordPress tables.
*
* categories, post2cat, and link2cat were deprecated in 2.3.0, db version 5539.
* 'categories', 'post2cat', and 'link2cat' were deprecated in 2.3.0, db version 5539.
*
* @since 2.9.0
* @see wpdb::tables()
@ -461,9 +466,10 @@ class wpdb {
public $sitemeta;
/**
* Format specifiers for DB columns. Columns not listed here default to %s. Initialized during WP load.
* Format specifiers for DB columns.
*
* Keys are column names, values are format types: 'ID' => '%d'
* Columns not listed here default to %s. Initialized during WP load.
* Keys are column names, values are format types: 'ID' => '%d'.
*
* @since 2.8.0
* @see wpdb::prepare()
@ -542,7 +548,7 @@ class wpdb {
/**
* Whether MySQL is used as the database engine.
*
* Set in WPDB::db_connect() to true, by default. This is used when checking
* Set in wpdb::db_connect() to true, by default. This is used when checking
* against the required MySQL version for WordPress. Normally, a replacement
* database drop-in (db.php) will skip these checks, but setting this to true
* will force the checks to occur.
@ -586,12 +592,12 @@ class wpdb {
/**
* 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.
* PHP5 style constructor for compatibility with PHP5. Does the actual setting up
* of the class properties and connection to the database.
*
* @link https://core.trac.wordpress.org/ticket/3354
* @since 2.0.8
*
* @link https://core.trac.wordpress.org/ticket/3354
* @global string $wp_version The WordPress version string.
*
* @param string $dbuser MySQL database user.
@ -632,7 +638,7 @@ class wpdb {
* @since 3.5.0
*
* @param string $name The private member to get, and optionally process.
* @return mixed The private member.
* @return mixed The private member.
*/
public function __get( $name ) {
if ( 'col_info' === $name ) {
@ -667,9 +673,8 @@ class wpdb {
*
* @since 3.5.0
*
* @param string $name The private member to check.
*
* @return bool If the member is set or not.
* @param string $name The private member to check.
* @return bool If the member is set or not.
*/
public function __isset( $name ) {
return isset( $this->$name );
@ -687,7 +692,7 @@ class wpdb {
}
/**
* Set $this->charset and $this->collate
* Sets $this->charset and $this->collate.
*
* @since 3.1.0
*/
@ -810,13 +815,13 @@ class wpdb {
}
/**
* Change the current SQL mode, and ensure its WordPress compatibility.
* Changes the current SQL mode, and ensures its WordPress compatibility.
*
* If no modes are passed, it will ensure the current MySQL server modes are compatible.
*
* @since 3.9.0
*
* @param array $modes Optional. A list of SQL modes to set.
* @param array $modes Optional. A list of SQL modes to set. Default empty array.
*/
public function set_sql_mode( $modes = array() ) {
if ( empty( $modes ) ) {
@ -879,7 +884,8 @@ class wpdb {
* @since 2.5.0
*
* @param string $prefix Alphanumeric name for the new prefix.
* @param bool $set_table_names Optional. Whether the table names, e.g. wpdb::$posts, should be updated or not.
* @param bool $set_table_names Optional. Whether the table names, e.g. wpdb::$posts,
* should be updated or not. Default true.
* @return string|WP_Error Old prefix or WP_Error on error.
*/
public function set_prefix( $prefix, $set_table_names = true ) {
@ -952,6 +958,7 @@ class wpdb {
* Gets blog prefix.
*
* @since 3.0.0
*
* @param int $blog_id Optional.
* @return string Blog prefix.
*/
@ -974,27 +981,30 @@ class wpdb {
/**
* Returns an array of WordPress tables.
*
* Also allows for the CUSTOM_USER_TABLE and CUSTOM_USER_META_TABLE to override the WordPress users and usermeta
* tables that would otherwise be determined by the prefix.
* Also allows for the CUSTOM_USER_TABLE and CUSTOM_USER_META_TABLE to override the WordPress users
* and usermeta tables that would otherwise be determined by the prefix.
*
* The $scope argument can take one of the following:
*
* 'all' - returns 'all' and 'global' tables. No old tables are returned.
* 'blog' - returns the blog-level tables for the queried blog.
* 'global' - returns the global tables for the installation, returning multisite tables only if running multisite.
* 'global' - returns the global tables for the installation, returning multisite tables only on multisite.
* 'ms_global' - returns the multisite global tables, regardless if current installation is multisite.
* 'old' - returns tables which are deprecated.
*
* @since 3.0.0
*
* @uses wpdb::$tables
* @uses wpdb::$old_tables
* @uses wpdb::$global_tables
* @uses wpdb::$ms_global_tables
*
* @param string $scope Optional. Can be all, global, ms_global, blog, or old tables. Defaults to all.
* @param bool $prefix Optional. Whether to include table prefixes. Default true. If blog
* prefix is requested, then the custom users and usermeta tables will be mapped.
* @param int $blog_id Optional. The blog_id to prefix. Defaults to wpdb::$blogid. Used only when prefix is requested.
* @param string $scope Optional. Possible values include 'all', 'global', 'ms_global', 'blog',
* or 'old' tables. Default 'all'.
* @param bool $prefix Optional. Whether to include table prefixes. If blog prefix is requested,
* then the custom users and usermeta tables will be mapped. Default true.
* @param int $blog_id Optional. The blog_id to prefix. Used only when prefix is requested.
* Defaults to wpdb::$blogid.
* @return array Table names. When a prefix is requested, the key is the unprefixed table name.
*/
public function tables( $scope = 'all', $prefix = true, $blog_id = 0 ) {
@ -1055,12 +1065,12 @@ class wpdb {
/**
* 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 a DB error.
* The database name will be changed based on the current database connection.
* On failure, the execution will bail and display a DB error.
*
* @since 0.71
*
* @param string $db MySQL database name
* @param string $db MySQL database name.
* @param resource|null $dbh Optional link identifier.
*/
public function select( $db, $dbh = null ) {
@ -1122,7 +1132,7 @@ class wpdb {
*
* @since 2.8.0
* @deprecated 3.6.0 Use wpdb::prepare()
* @see wpdb::prepare
* @see wpdb::prepare()
* @see esc_sql()
*
* @param string $string
@ -1136,11 +1146,12 @@ class wpdb {
}
/**
* Real escape, using mysqli_real_escape_string() or mysql_real_escape_string()
* Real escape, using mysqli_real_escape_string() or mysql_real_escape_string().
*
* @since 2.8.0
*
* @see mysqli_real_escape_string()
* @see mysql_real_escape_string()
* @since 2.8.0
*
* @param string $string String to escape.
* @return string Escaped string.
@ -1167,10 +1178,11 @@ class wpdb {
}
/**
* Escape data. Works on arrays.
* Escapes data. Works on arrays.
*
* @since 2.8.0
*
* @uses wpdb::_real_escape()
* @since 2.8.0
*
* @param string|array $data Data to escape.
* @return string|array Escaped data, in the same type as supplied.
@ -1201,8 +1213,8 @@ class wpdb {
* @see wpdb::prepare()
* @see esc_sql()
*
* @param mixed $data
* @return mixed
* @param string|array $data Data to escape.
* @return string|array Escaped data, in the same type as supplied.
*/
public function escape( $data ) {
if ( func_num_args() === 1 && function_exists( '_deprecated_function' ) ) {
@ -1246,37 +1258,39 @@ class wpdb {
* %f (float)
* %s (string)
*
* All placeholders MUST be left unquoted in the query string. A corresponding argument MUST be passed for each
* placeholder.
* All placeholders MUST be left unquoted in the query string. A corresponding argument
* MUST be passed for each placeholder.
*
* Note: There is one exception to the above: for compatibility with old behavior, older-style numbered or formatted
* string placeholders (eg, %1$s, %5s) will not have quotes added by this function, so should be passed with
* appropriate quotes around them.
* Note: There is one exception to the above: for compatibility with old behavior,
* numbered or formatted string placeholders (eg, %1$s, %5s) will not have quotes
* added by this function, so should be passed with appropriate quotes around them.
*
* Literal percentage signs (%) in the query string must be written as %%. Percentage wildcards (for example,
* to use in LIKE syntax) must be passed via a substitution argument containing the complete LIKE string, these
* cannot be inserted directly in the query string. Also see wpdb::esc_like().
* Literal percentage signs (%) in the query string must be written as %%. Percentage wildcards
* (for example, to use in LIKE syntax) must be passed via a substitution argument containing
* the complete LIKE string, these cannot be inserted directly in the query string.
* Also see wpdb::esc_like().
*
* Arguments may be passed as individual arguments to the method, or as a single array containing all arguments.
* A combination of the two is not supported.
* Arguments may be passed as individual arguments to the method, or as a single array
* containing all arguments. A combination of the two is not supported.
*
* Examples:
* $wpdb->prepare( "SELECT * FROM `table` WHERE `column` = %s AND `field` = %d OR `other_field` LIKE %s", array( 'foo', 1337, '%bar' ) );
* $wpdb->prepare( "SELECT DATE_FORMAT(`field`, '%%c') FROM `table` WHERE `column` = %s", 'foo' );
*
* @link https://www.php.net/sprintf Description of syntax.
* @since 2.3.0
* @since 5.3.0 Formalized the existing and already documented `...$args` parameter
* by updating the function signature. The second parameter was changed
* from `$args` to `...$args`.
*
* @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
* with an array of arguments, or the first variable to substitute into the query's
* placeholders if being called with individual arguments.
* @param mixed ...$args Further variables to substitute into the query's placeholders if being called with
* individual arguments.
* @link https://www.php.net/sprintf Description of syntax.
*
* @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 with an array of arguments, or the first variable
* to substitute into the query's placeholders if being called with
* individual arguments.
* @param mixed ...$args Further variables to substitute into the query's placeholders
* if being called with individual arguments.
* @return string|void Sanitized query string, if there is a query to prepare.
*/
public function prepare( $query, ...$args ) {
@ -1388,7 +1402,7 @@ class wpdb {
/**
* First half of escaping for LIKE special characters % and _ before preparing for MySQL.
*
* Use this only before wpdb::prepare() or esc_sql(). Reversing the order is very bad for security.
* Use this only before wpdb::prepare() or esc_sql(). Reversing the order is very bad for security.
*
* Example Prepared Statement:
*
@ -1403,22 +1417,23 @@ class wpdb {
*
* @since 4.0.0
*
* @param string $text The raw text to be escaped. The input typed by the user should have no
* extra or deleted slashes.
* @return string Text in the form of a LIKE phrase. The output is not SQL safe. Call $wpdb::prepare()
* or real_escape next.
* @param string $text The raw text to be escaped. The input typed by the user
* should have no extra or deleted slashes.
* @return string Text in the form of a LIKE phrase. The output is not SQL safe.
* Call wpdb::prepare() or wpdb::_real_escape() next.
*/
public function esc_like( $text ) {
return addcslashes( $text, '_%\\' );
}
/**
* Print SQL/DB error.
* Prints 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
* @global array $EZSQL_ERROR Stores error information of query and error string.
*
* @param string $str The error to display.
* @return void|false Void if the showing of errors is enabled, false if disabled.
*/
public function print_error( $str = '' ) {
@ -1489,15 +1504,14 @@ class wpdb {
/**
* 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.
*
* @see wpdb::hide_errors()
* This function should be used only to enable showing of errors.
* wpdb::hide_errors() should be used instead for hiding errors.
*
* @since 0.71
*
* @see wpdb::hide_errors()
*
* @param bool $show Whether to show or hide errors.
* @param bool $show Optional. Whether to show errors. Default true.
* @return bool Whether showing of errors was previously active.
*/
public function show_errors( $show = true ) {
@ -1512,6 +1526,7 @@ class wpdb {
* By default database errors are not shown.
*
* @since 0.71
*
* @see wpdb::show_errors()
*
* @return bool Whether showing of errors was previously active.
@ -1523,15 +1538,16 @@ class wpdb {
}
/**
* Whether to suppress database errors.
* Enables or disables suppressing of database errors.
*
* By default database errors are suppressed, with a simple call to this function they can be enabled.
* By default database errors are suppressed.
*
* @since 2.5.0
*
* @see wpdb::hide_errors()
*
* @param bool $suppress Optional. New value. Defaults to true.
* @return bool Old value
* @param bool $suppress Optional. Whether to suppress errors. Default true.
* @return bool Whether suppressing of errors was previously active.
*/
public function suppress_errors( $suppress = true ) {
$errors = $this->suppress_errors;
@ -1540,7 +1556,7 @@ class wpdb {
}
/**
* Kill cached query results.
* Kills cached query results.
*
* @since 0.71
*/
@ -1571,7 +1587,7 @@ class wpdb {
}
/**
* Connect to and select database.
* Connects to and selects database.
*
* If $allow_bail is false, the lack of database connection will need to be handled manually.
*
@ -1605,9 +1621,8 @@ class wpdb {
}
/*
* If using the `mysqlnd` library, the IPv6 address needs to be
* enclosed in square brackets, whereas it doesn't while using the
* `libmysqlclient` library.
* If using the `mysqlnd` library, the IPv6 address needs to be enclosed
* in square brackets, whereas it doesn't while using the `libmysqlclient` library.
* @see https://bugs.php.net/bug.php?id=67563
*/
if ( $is_ipv6 && extension_loaded( 'mysqlnd' ) ) {
@ -1707,17 +1722,18 @@ class wpdb {
}
/**
* Parse the DB_HOST setting to interpret it for mysqli_real_connect.
* Parses the DB_HOST setting to interpret it for mysqli_real_connect().
*
* mysqli_real_connect doesn't support the host param including a port or socket like mysql_connect does. This
* duplicates how mysql_connect detects a port and/or socket file.
* mysqli_real_connect() doesn't support the host param including a port or socket
* like mysql_connect() does. This duplicates how mysql_connect() detects a port
* and/or socket file.
*
* @since 4.9.0
*
* @param string $host The DB_HOST setting to parse.
* @return array|bool Array containing the host, the port, the socket and whether
* it is an IPv6 address, in that order. If $host couldn't be parsed,
* returns false.
* @return array|false Array containing the host, the port, the socket and
* whether it is an IPv6 address, in that order.
* False if $host couldn't be parsed.
*/
public function parse_db_host( $host ) {
$port = null;
@ -1762,8 +1778,8 @@ class wpdb {
/**
* Checks that the connection to the database is still up. If not, try to reconnect.
*
* If this function is unable to reconnect, it will forcibly die, or if after the {@see 'template_redirect'} hook
* has been fired, return false instead.
* If this function is unable to reconnect, it will forcibly die, or if called
* after the {@see 'template_redirect'} hook has been fired, return false instead.
*
* If $allow_bail is false, the lack of database connection will need to be handled manually.
*
@ -1792,8 +1808,8 @@ class wpdb {
}
for ( $tries = 1; $tries <= $this->reconnect_retries; $tries++ ) {
// On the last try, re-enable warnings. We want to see a single instance of the
// "unable to connect" message on the bail() screen, if it appears.
// On the last try, re-enable warnings. We want to see a single instance
// of the "unable to connect" message on the bail() screen, if it appears.
if ( $this->reconnect_retries === $tries && WP_DEBUG ) {
error_reporting( $error_reporting );
}
@ -1843,18 +1859,21 @@ class wpdb {
// We weren't able to reconnect, so we better bail.
$this->bail( $message, 'db_connect_fail' );
// Call dead_db() if bail didn't die, because this database is no more. It has ceased to be (at least temporarily).
// Call dead_db() if bail didn't die, because this database is no more.
// It has ceased to be (at least temporarily).
dead_db();
}
/**
* Perform a MySQL database query, using current database connection.
* Performs a MySQL database query, using current database connection.
*
* More information can be found on the codex page.
* More information can be found on the Codex page.
*
* @since 0.71
*
* @param string $query Database query
* @link https://codex.wordpress.org/Function_Reference/wpdb_Class
*
* @param string $query Database query.
* @return int|bool Boolean true for CREATE, ALTER, TRUNCATE and DROP queries. Number of rows
* affected/selected for all other queries. Boolean false on error.
*/
@ -1986,7 +2005,7 @@ class wpdb {
}
}
// Log number of rows the query returned and return number of rows selected.
// Log and return the number of rows selected.
$this->num_rows = $num_rows;
$return_val = $num_rows;
}
@ -2033,10 +2052,9 @@ class wpdb {
*
* @param string $query The query's SQL.
* @param float $query_time Total time spent on the query, in seconds.
* @param string $query_callstack Comma separated list of the calling functions.
* @param string $query_callstack Comma-separated list of the calling functions.
* @param float $query_start Unix timestamp of the time at the start of the query.
* @param array $query_data Custom query data.
* }
*/
public function log_query( $query, $query_time, $query_callstack, $query_start, $query_data ) {
/**
@ -2051,7 +2069,7 @@ class wpdb {
* @param array $query_data Custom query data.
* @param string $query The query's SQL.
* @param float $query_time Total time spent on the query, in seconds.
* @param string $query_callstack Comma separated list of the calling functions.
* @param string $query_callstack Comma-separated list of the calling functions.
* @param float $query_start Unix timestamp of the time at the start of the query.
*/
$query_data = apply_filters( 'log_query_custom_data', $query_data, $query, $query_time, $query_callstack, $query_start );
@ -2124,13 +2142,14 @@ class wpdb {
}
/**
* Insert a row into a table.
* Inserts a row into the table.
*
* Examples:
* wpdb::insert( 'table', array( 'column' => 'foo', 'field' => 'bar' ) )
* wpdb::insert( 'table', array( 'column' => 'foo', 'field' => 1337 ), array( '%s', '%d' ) )
*
* @since 2.5.0
*
* @see wpdb::prepare()
* @see wpdb::$field_types
* @see wp_set_wpdb_vars()
@ -2152,13 +2171,14 @@ class wpdb {
}
/**
* Replace a row into a table.
* Replaces a row in the table.
*
* Examples:
* wpdb::replace( 'table', array( 'column' => 'foo', 'field' => 'bar' ) )
* wpdb::replace( 'table', array( 'column' => 'foo', 'field' => 1337 ), array( '%s', '%d' ) )
*
* @since 3.0.0
*
* @see wpdb::prepare()
* @see wpdb::$field_types
* @see wp_set_wpdb_vars()
@ -2185,11 +2205,12 @@ class wpdb {
* Runs an insert or replace query based on $type argument.
*
* @since 3.0.0
*
* @see wpdb::prepare()
* @see wpdb::$field_types
* @see wp_set_wpdb_vars()
*
* @param string $table Table name
* @param string $table Table name.
* @param array $data Data to insert (in column => value pairs).
* Both $data columns and $data values should be "raw" (neither should be SQL escaped).
* Sending a null value will cause the column to be set to NULL - the corresponding
@ -2199,7 +2220,8 @@ class wpdb {
* A format is one of '%d', '%f', '%s' (integer, float, string).
* If omitted, all values in $data will be treated as strings unless otherwise
* specified in wpdb::$field_types.
* @param string $type Optional. What type of operation is this? INSERT or REPLACE. Defaults to INSERT.
* @param string $type Optional. Type of operation. Possible values include 'INSERT' or 'REPLACE'.
* Default 'INSERT'.
* @return int|false The number of rows affected, or false on error.
*/
function _insert_replace_helper( $table, $data, $format = null, $type = 'INSERT' ) {
@ -2236,18 +2258,19 @@ class wpdb {
}
/**
* Update a row in the table.
* Updates a row in the table.
*
* Examples:
* wpdb::update( 'table', array( 'column' => 'foo', 'field' => 'bar' ), array( 'ID' => 1 ) )
* wpdb::update( 'table', array( 'column' => 'foo', 'field' => 1337 ), array( 'ID' => 1 ), array( '%s', '%d' ), array( '%d' ) )
*
* @since 2.5.0
*
* @see wpdb::prepare()
* @see wpdb::$field_types
* @see wp_set_wpdb_vars()
*
* @param string $table Table name
* @param string $table Table name.
* @param array $data Data to update (in column => value pairs).
* Both $data columns and $data values should be "raw" (neither should be SQL escaped).
* Sending a null value will cause the column to be set to NULL - the corresponding
@ -2314,17 +2337,19 @@ class wpdb {
}
/**
* Delete a row in the table
* Deletes a row in the table.
*
* Examples:
* wpdb::delete( 'table', array( 'ID' => 1 ) )
* wpdb::delete( 'table', array( 'ID' => 1 ), array( '%d' ) )
*
* @since 3.4.0
*
* @see wpdb::prepare()
* @see wpdb::$field_types
* @see wp_set_wpdb_vars()
*
* @param string $table Table name
* @param string $table Table name.
* @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".
@ -2370,19 +2395,19 @@ class wpdb {
/**
* Processes arrays of field/value pairs and field formats.
*
* This is a helper method for wpdb's CRUD methods, which take field/value pairs for inserts, updates, and where
* clauses. This method first pairs each value with a format. Then it determines the charset of that field, using
* that to determine if any invalid text would be stripped. If text is stripped, then field processing is rejected
* and the query fails.
* This is a helper method for wpdb's CRUD methods, which take field/value pairs
* for inserts, updates, and where clauses. This method first pairs each value
* with a format. Then it determines the charset of that field, using that
* to determine if any invalid text would be stripped. If text is stripped,
* then field processing is rejected and the query fails.
*
* @since 4.2.0
*
* @param string $table Table name.
* @param array $data Field/value pair.
* @param mixed $format Format for each field.
*
* @return array|false Returns an array of fields that contain paired value and formats. Returns false for
* invalid values.
* @return array|false An array of fields that contain paired value and formats.
* False for invalid values.
*/
protected function process_fields( $table, $data, $format ) {
$data = $this->process_field_formats( $data, $format );
@ -2416,7 +2441,8 @@ class wpdb {
*
* @param array $data Array of fields to values.
* @param mixed $format Formats to be mapped to the values in $data.
* @return array Array, keyed by field names with values being an array of 'value' and 'format' keys.
* @return array Array, keyed by field names with values being an array
* of 'value' and 'format' keys.
*/
protected function process_field_formats( $data, $format ) {
$formats = (array) $format;
@ -2444,13 +2470,14 @@ class wpdb {
}
/**
* Adds field charsets to field/value/format arrays generated by the wpdb::process_field_formats() method.
* Adds field charsets to field/value/format arrays generated by wpdb::process_field_formats().
*
* @since 4.2.0
*
* @param array $data As it comes from the wpdb::process_field_formats() method.
* @param string $table Table name.
* @return array|false The same array as $data with additional 'charset' keys.
* False on failure.
*/
protected function process_field_charsets( $data, $table ) {
foreach ( $data as $field => $value ) {
@ -2474,7 +2501,7 @@ class wpdb {
}
/**
* For string fields, record the maximum string length that field can safely save.
* For string fields, records the maximum string length that field can safely save.
*
* @since 4.2.1
*
@ -2505,18 +2532,19 @@ class wpdb {
}
/**
* Retrieve one variable from the database.
* Retrieves one variable from the database.
*
* 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, the value in the column and row specified is returned. If $query is null, the value
* in the specified column and row from the previous SQL result is returned.
* 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,
* the value in the column and row specified is returned. If $query is null,
* the value in the specified column and row from the previous SQL result is returned.
*
* @since 0.71
*
* @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|null Database query result (as string), or null on failure
* @return string|null Database query result (as string), or null on failure.
*/
public function get_var( $query = null, $x = 0, $y = 0 ) {
$this->func_call = "\$db->get_var(\"$query\", $x, $y)";
@ -2529,28 +2557,28 @@ class wpdb {
$this->query( $query );
}
// Extract var out of cached results based x,y vals.
// Extract var out of cached results based on x,y vals.
if ( ! empty( $this->last_result[ $y ] ) ) {
$values = array_values( get_object_vars( $this->last_result[ $y ] ) );
}
// If there is a value return it else return null.
// If there is a value return it, else return null.
return ( isset( $values[ $x ] ) && '' !== $values[ $x ] ) ? $values[ $x ] : null;
}
/**
* Retrieve one row from the database.
* Retrieves one row from the database.
*
* Executes a SQL query and returns the row from the SQL result.
*
* @since 0.71
*
* @param string|null $query SQL query.
* @param string $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which
* correspond to a stdClass object, an associative array, or a numeric array,
* respectively. Default OBJECT.
* @param string $output Optional. The required return type. Possible values include
* OBJECT, ARRAY_A, or ARRAY_N, which correspond to an stdClass object,
* an associative array, or a numeric array, respectively. Default OBJECT.
* @param int $y Optional. Row to return. Indexed from 0.
* @return array|object|null|void Database query result in format specified by $output or null on failure
* @return array|object|null|void Database query result in format specified by $output or null on failure.
*/
public function get_row( $query = null, $output = OBJECT, $y = 0 ) {
$this->func_call = "\$db->get_row(\"$query\",$output,$y)";
@ -2584,11 +2612,11 @@ class wpdb {
}
/**
* Retrieve one column from the database.
* Retrieves 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.
* Executes a SQL query and returns the column from the SQL result.
* If the SQL result contains more than one column, the column specified is returned.
* If $query is null, the specified column from the previous SQL result is returned.
*
* @since 0.71
*
@ -2616,7 +2644,7 @@ class wpdb {
}
/**
* Retrieve an entire SQL result set from the database (i.e., many rows)
* Retrieves an entire SQL result set from the database (i.e., many rows).
*
* Executes a SQL query and returns the entire SQL result.
*
@ -2624,11 +2652,12 @@ class wpdb {
*
* @param string $query SQL query.
* @param string $output Optional. Any 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.
* 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 array|object|null Database query results.
*
*/
@ -2791,8 +2820,8 @@ class wpdb {
*
* @param string $table Table name.
* @param string $column Column name.
* @return string|false|WP_Error Column character set as a string. False if the column has no character set.
* WP_Error object if there was an error.
* @return string|false|WP_Error Column character set as a string. False if the column has
* no character set. WP_Error object if there was an error.
*/
public function get_col_charset( $table, $column ) {
$tablekey = strtolower( $table );
@ -2848,7 +2877,7 @@ class wpdb {
}
/**
* Retrieve the maximum string length allowed in a given column.
* Retrieves the maximum string length allowed in a given column.
*
* The length may either be specified as a byte length or a character length.
*
@ -2856,8 +2885,8 @@ class wpdb {
*
* @param string $table Table name.
* @param string $column Column name.
* @return array|false|WP_Error array( 'length' => (int), 'type' => 'byte' | 'char' )
* false if the column has no length (for example, numeric column)
* @return array|false|WP_Error array( 'length' => (int), 'type' => 'byte' | 'char' ).
* False if the column has no length (for example, numeric column).
* WP_Error object if there was an error.
*/
public function get_col_length( $table, $column ) {
@ -2939,10 +2968,10 @@ class wpdb {
}
/**
* Check if a string is ASCII.
* Checks if a string is ASCII.
*
* The negative regex is faster for non-ASCII strings, as it allows the search to finish as soon as it encounters
* a non-ASCII character.
* The negative regex is faster for non-ASCII strings, as it allows
* the search to finish as soon as it encounters a non-ASCII character.
*
* @since 4.2.0
*
@ -2962,7 +2991,7 @@ class wpdb {
}
/**
* Check if the query is accessing a collation considered safe on the current version of MySQL.
* Checks if the query is accessing a collation considered safe on the current version of MySQL.
*
* @since 4.2.0
*
@ -3023,11 +3052,12 @@ class wpdb {
*
* @since 4.2.0
*
* @param array $data Array of value arrays. Each value array has the keys 'value' and 'charset'. An optional
* 'ascii' key can be set to false to avoid redundant ASCII checks.
* @return array|WP_Error The $data parameter, with invalid characters removed from each value. This works as a
* passthrough: any additional keys such as 'field' are retained in each value array. If we
* cannot remove invalid characters, a WP_Error object is returned.
* @param array $data Array of value arrays. Each value array has the keys 'value' and 'charset'.
* An optional 'ascii' key can be set to false to avoid redundant ASCII checks.
* @return array|WP_Error The $data parameter, with invalid characters removed from each value.
* This works as a passthrough: any additional keys such as 'field' are
* retained in each value array. If we cannot remove invalid characters,
* a WP_Error object is returned.
*/
protected function strip_invalid_text( $data ) {
$db_check_string = false;
@ -3040,8 +3070,8 @@ class wpdb {
$truncate_by_byte_length = 'byte' === $value['length']['type'];
} else {
$length = false;
// Since we have no length, we'll never truncate. Initialize the variable to false. true would take us
// through an unnecessary (for this case) codepath below.
// Since we have no length, we'll never truncate. Initialize the variable to false.
// True would take us through an unnecessary (for this case) codepath below.
$truncate_by_byte_length = false;
}
@ -3180,7 +3210,7 @@ class wpdb {
*
* @since 4.2.0
*
* @param string $query Query to convert.
* @param string $query Query to convert.
* @return string|WP_Error The converted query, or a WP_Error object if the conversion fails.
*/
protected function strip_invalid_text_from_query( $query ) {
@ -3261,7 +3291,7 @@ class wpdb {
}
/**
* Find the first table name referenced in a query.
* Finds the first table name referenced in a query.
*
* @since 4.2.0
*
@ -3300,9 +3330,10 @@ class wpdb {
/*
* SHOW TABLE STATUS LIKE and SHOW TABLES LIKE 'wp\_123\_%'
* This quoted LIKE operand seldom holds a full table name. It is usually a
* pattern for matching a prefix so we just strip the trailing % and unescape
* the _ to get 'wp_123_' which drop-ins can use for routing these SQL statements.
* This quoted LIKE operand seldom holds a full table name.
* It is usually a pattern for matching a prefix so we just
* strip the trailing % and unescape the _ to get 'wp_123_'
* which drop-ins can use for routing these SQL statements.
*/
if ( preg_match( '/^\s*SHOW\s+(?:TABLE\s+STATUS|(?:FULL\s+)?TABLES)\s+(?:WHERE\s+Name\s+)?LIKE\s*("|\')((?:[\\\\0-9a-zA-Z$_.-]|[\xC2-\xDF][\x80-\xBF])+)%?\\1/is', $query, $maybe ) ) {
return str_replace( '\\_', '_', $maybe[2] );
@ -3335,7 +3366,7 @@ class wpdb {
}
/**
* Load the column metadata from the last query.
* Loads the column metadata from the last query.
*
* @since 3.5.0
*/
@ -3358,15 +3389,16 @@ class wpdb {
}
/**
* Retrieve column metadata from the last query.
* Retrieves column metadata from the last query.
*
* @since 0.71
*
* @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 string $info_type Optional. Possible values include 'name', 'table', 'def', 'max_length',
* 'not_null', 'primary_key', 'multiple_key', 'unique_key', 'numeric',
* 'blob', 'type', 'unsigned', 'zerofill'. Default 'name'.
* @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
* 3: if the col is numeric. 4: col's type. Default -1.
* @return mixed Column results.
*/
public function get_col_info( $info_type = 'name', $col_offset = -1 ) {
$this->load_col_info();
@ -3416,9 +3448,10 @@ class wpdb {
*
* @since 1.5.0
*
* @param string $message The Error message
* @param string $error_code Optional. A Computer readable string to identify the error.
* @return false|void
* @param string $message The error message.
* @param string $error_code Optional. A computer-readable string to identify the error.
* Default '500'.
* @return void|false Void if the showing of errors is enabled, false if disabled.
*/
public function bail( $message, $error_code = '500' ) {
if ( $this->show_errors ) {
@ -3460,7 +3493,8 @@ class wpdb {
*
* @since 4.5.0
*
* @return bool True if the connection was successfully closed, false if it wasn't, or if the connection doesn't exist.
* @return bool True if the connection was successfully closed,
* false if it wasn't, or if the connection doesn't exist.
*/
public function close() {
if ( ! $this->dbh ) {
@ -3483,13 +3517,13 @@ class wpdb {
}
/**
* Whether MySQL database is at least the required minimum version.
* Determines whether MySQL database is at least the required minimum version.
*
* @since 2.5.0
*
* @global string $wp_version
* @global string $required_mysql_version
* @return WP_Error|void
* @global string $wp_version The WordPress version string.
* @global string $required_mysql_version The required MySQL version string.
* @return void|WP_Error
*/
public function check_database_version() {
global $wp_version, $required_mysql_version;
@ -3501,7 +3535,7 @@ class wpdb {
}
/**
* Whether the database supports collation.
* Determines whether the database supports collation.
*
* Called when WordPress is generating the table scheme.
*
@ -3510,7 +3544,7 @@ class wpdb {
* @since 2.5.0
* @deprecated 3.5.0 Use wpdb::has_cap()
*
* @return bool True if collation is supported, false if version does not
* @return bool True if collation is supported, false if not.
*/
public function supports_collation() {
_deprecated_function( __FUNCTION__, '3.5.0', 'wpdb::has_cap( \'collation\' )' );
@ -3518,7 +3552,7 @@ class wpdb {
}
/**
* The database character collate.
* Retrieves the database character collate.
*
* @since 3.5.0
*
@ -3538,7 +3572,7 @@ class wpdb {
}
/**
* Determine if a database supports a particular feature.
* Determines if a database supports a particular feature.
*
* @since 2.7.0
* @since 4.1.0 Added support for the 'utf8mb4' feature.
@ -3546,8 +3580,8 @@ class wpdb {
*
* @see wpdb::db_version()
*
* @param string $db_cap The feature to check for. Accepts 'collation', 'group_concat', 'subqueries', 'set_charset',
* 'utf8mb4', or 'utf8mb4_520'.
* @param string $db_cap The feature to check for. Accepts 'collation', 'group_concat',
* 'subqueries', 'set_charset', 'utf8mb4', or 'utf8mb4_520'.
* @return int|false Whether the database feature is supported, false otherwise.
*/
public function has_cap( $db_cap ) {
@ -3588,13 +3622,14 @@ class wpdb {
}
/**
* Retrieve the name of the function that called wpdb.
* Retrieves the name of the function that called wpdb.
*
* Searches up the list of functions until it reaches the one that would most logically had called this method.
* 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 Comma separated list of the calling functions.
* @return string Comma-separated list of the calling functions.
*/
public function get_caller() {
return wp_debug_backtrace_summary( __CLASS__ );