sergiotarxz
/
Wordpress
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

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

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

See #49572.

git-svn-id: https://develop.svn.wordpress.org/trunk@47749 602fd350-edb4-49c9-b593-d223f7449a82
This commit is contained in:
Sergey Biryukov 2020-05-03 11:43:14 +00:00
parent 84772cc608
commit 5dbed96333
1 changed files with 213 additions and 178 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -37,10 +37,15 @@ define( 'ARRAY_A', 'ARRAY_A' );
define( 'ARRAY_N', 'ARRAY_N' ); 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 * This class is used to interact with a database without needing to use raw SQL statements.
* uses this class to instantiate the global $wpdb object, providing access to the WordPress database. * 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/ * @link https://developer.wordpress.org/reference/classes/wpdb/
* *
@ -67,7 +72,7 @@ class wpdb {
var $suppress_errors = false; var $suppress_errors = false;
/** /**
* The last error encountered during the last query. * The error encountered during the last query.
* *
* @since 2.5.0 * @since 2.5.0
* @var string * @var string
@ -187,7 +192,7 @@ class wpdb {
* *
* @type string $0 The query's SQL. * @type string $0 The query's SQL.
* @type float $1 Total time spent on the query, in seconds. * @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 float $3 Unix timestamp of the time at the start of the query.
* @type array $4 Custom query data. * @type array $4 Custom query data.
* } * }
@ -270,7 +275,7 @@ class wpdb {
/** /**
* List of deprecated WordPress tables. * 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 * @since 2.9.0
* @see wpdb::tables() * @see wpdb::tables()
@ -461,9 +466,10 @@ class wpdb {
public $sitemeta; 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 * @since 2.8.0
* @see wpdb::prepare() * @see wpdb::prepare()
@ -542,7 +548,7 @@ class wpdb {
/** /**
* Whether MySQL is used as the database engine. * 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 * against the required MySQL version for WordPress. Normally, a replacement
* database drop-in (db.php) will skip these checks, but setting this to true * database drop-in (db.php) will skip these checks, but setting this to true
* will force the checks to occur. * will force the checks to occur.
@ -586,12 +592,12 @@ class wpdb {
/** /**
* Connects to the database server and selects a database. * 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 * PHP5 style constructor for compatibility with PHP5. Does the actual setting up
* connection to the database. * of the class properties and connection to the database.
* *
* @link https://core.trac.wordpress.org/ticket/3354
* @since 2.0.8 * @since 2.0.8
* *
* @link https://core.trac.wordpress.org/ticket/3354
* @global string $wp_version The WordPress version string. * @global string $wp_version The WordPress version string.
* *
* @param string $dbuser MySQL database user. * @param string $dbuser MySQL database user.
@ -632,7 +638,7 @@ class wpdb {
* @since 3.5.0 * @since 3.5.0
* *
* @param string $name The private member to get, and optionally process. * @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 ) { public function __get( $name ) {
if ( 'col_info' === $name ) { if ( 'col_info' === $name ) {
@ -667,9 +673,8 @@ class wpdb {
* *
* @since 3.5.0 * @since 3.5.0
* *
* @param string $name The private member to check. * @param string $name The private member to check.
* * @return bool If the member is set or not.
* @return bool If the member is set or not.
*/ */
public function __isset( $name ) { public function __isset( $name ) {
return isset( $this->$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 * @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. * If no modes are passed, it will ensure the current MySQL server modes are compatible.
* *
* @since 3.9.0 * @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() ) { public function set_sql_mode( $modes = array() ) {
if ( empty( $modes ) ) { if ( empty( $modes ) ) {
@ -879,7 +884,8 @@ class wpdb {
* @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.
* @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. * @return string|WP_Error Old prefix or WP_Error on error.
*/ */
public function set_prefix( $prefix, $set_table_names = true ) { public function set_prefix( $prefix, $set_table_names = true ) {
@ -952,6 +958,7 @@ class wpdb {
* Gets blog prefix. * Gets blog prefix.
* *
* @since 3.0.0 * @since 3.0.0
*
* @param int $blog_id Optional. * @param int $blog_id Optional.
* @return string Blog prefix. * @return string Blog prefix.
*/ */
@ -974,27 +981,30 @@ class wpdb {
/** /**
* Returns an array of WordPress tables. * 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 * Also allows for the CUSTOM_USER_TABLE and CUSTOM_USER_META_TABLE to override the WordPress users
* tables that would otherwise be determined by the prefix. * and usermeta tables that would otherwise be determined by the prefix.
* *
* The $scope argument can take one of the following: * The $scope argument can take one of the following:
* *
* 'all' - returns 'all' and 'global' tables. No old tables are returned. * 'all' - returns 'all' and 'global' tables. No old tables are returned.
* 'blog' - returns the blog-level tables for the queried blog. * '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. * 'ms_global' - returns the multisite global tables, regardless if current installation is multisite.
* 'old' - returns tables which are deprecated. * 'old' - returns tables which are deprecated.
* *
* @since 3.0.0 * @since 3.0.0
*
* @uses wpdb::$tables * @uses wpdb::$tables
* @uses wpdb::$old_tables * @uses wpdb::$old_tables
* @uses wpdb::$global_tables * @uses wpdb::$global_tables
* @uses wpdb::$ms_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 string $scope Optional. Possible values include 'all', 'global', 'ms_global', 'blog',
* @param bool $prefix Optional. Whether to include table prefixes. Default true. If blog * or 'old' tables. Default 'all'.
* prefix is requested, then the custom users and usermeta tables will be mapped. * @param bool $prefix Optional. Whether to include table prefixes. If blog prefix is requested,
* @param int $blog_id Optional. The blog_id to prefix. Defaults to wpdb::$blogid. Used only when 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. * @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 ) { public function tables( $scope = 'all', $prefix = true, $blog_id = 0 ) {
@ -1055,12 +1065,12 @@ class wpdb {
/** /**
* Selects a database using the current database connection. * 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 * The database name will be changed based on the current database connection.
* bail and display a DB error. * On failure, the execution will bail and display a DB error.
* *
* @since 0.71 * @since 0.71
* *
* @param string $db MySQL database name * @param string $db MySQL database name.
* @param resource|null $dbh Optional link identifier. * @param resource|null $dbh Optional link identifier.
*/ */
public function select( $db, $dbh = null ) { public function select( $db, $dbh = null ) {
@ -1122,7 +1132,7 @@ class wpdb {
* *
* @since 2.8.0 * @since 2.8.0
* @deprecated 3.6.0 Use wpdb::prepare() * @deprecated 3.6.0 Use wpdb::prepare()
* @see wpdb::prepare * @see wpdb::prepare()
* @see esc_sql() * @see esc_sql()
* *
* @param string $string * @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 mysqli_real_escape_string()
* @see mysql_real_escape_string() * @see mysql_real_escape_string()
* @since 2.8.0
* *
* @param string $string String to escape. * @param string $string String to escape.
* @return string Escaped string. * @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() * @uses wpdb::_real_escape()
* @since 2.8.0
* *
* @param string|array $data Data to escape. * @param string|array $data Data to escape.
* @return string|array Escaped data, in the same type as supplied. * @return string|array Escaped data, in the same type as supplied.
@ -1201,8 +1213,8 @@ class wpdb {
* @see wpdb::prepare() * @see wpdb::prepare()
* @see esc_sql() * @see esc_sql()
* *
* @param mixed $data * @param string|array $data Data to escape.
* @return mixed * @return string|array Escaped data, in the same type as supplied.
*/ */
public function escape( $data ) { public function escape( $data ) {
if ( func_num_args() === 1 && function_exists( '_deprecated_function' ) ) { if ( func_num_args() === 1 && function_exists( '_deprecated_function' ) ) {
@ -1246,37 +1258,39 @@ class wpdb {
* %f (float) * %f (float)
* %s (string) * %s (string)
* *
* All placeholders MUST be left unquoted in the query string. A corresponding argument MUST be passed for each * All placeholders MUST be left unquoted in the query string. A corresponding argument
* placeholder. * MUST be passed for each placeholder.
* *
* Note: There is one exception to the above: for compatibility with old behavior, older-style numbered or formatted * Note: There is one exception to the above: for compatibility with old behavior,
* string placeholders (eg, %1$s, %5s) will not have quotes added by this function, so should be passed with * numbered or formatted string placeholders (eg, %1$s, %5s) will not have quotes
* appropriate quotes around them. * 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, * Literal percentage signs (%) in the query string must be written as %%. Percentage wildcards
* to use in LIKE syntax) must be passed via a substitution argument containing the complete LIKE string, these * (for example, to use in LIKE syntax) must be passed via a substitution argument containing
* cannot be inserted directly in the query string. Also see wpdb::esc_like(). * 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. * Arguments may be passed as individual arguments to the method, or as a single array
* A combination of the two is not supported. * containing all arguments. A combination of the two is not supported.
* *
* Examples: * Examples:
* $wpdb->prepare( "SELECT * FROM `table` WHERE `column` = %s AND `field` = %d OR `other_field` LIKE %s", array( 'foo', 1337, '%bar' ) ); * $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' ); * $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 2.3.0
* @since 5.3.0 Formalized the existing and already documented `...$args` parameter * @since 5.3.0 Formalized the existing and already documented `...$args` parameter
* by updating the function signature. The second parameter was changed * by updating the function signature. The second parameter was changed
* from `$args` to `...$args`. * from `$args` to `...$args`.
* *
* @param string $query Query statement with sprintf()-like placeholders. * @link https://www.php.net/sprintf Description of syntax.
* @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.
* *
* @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. * @return string|void Sanitized query string, if there is a query to prepare.
*/ */
public function prepare( $query, ...$args ) { public function prepare( $query, ...$args ) {
@ -1388,7 +1402,7 @@ class wpdb {
/** /**
* First half of escaping for LIKE special characters % and _ before preparing for MySQL. * 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: * Example Prepared Statement:
* *
@ -1403,22 +1417,23 @@ class wpdb {
* *
* @since 4.0.0 * @since 4.0.0
* *
* @param string $text The raw text to be escaped. The input typed by the user should have no * @param string $text The raw text to be escaped. The input typed by the user
* extra or deleted slashes. * 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() * @return string Text in the form of a LIKE phrase. The output is not SQL safe.
* or real_escape next. * Call wpdb::prepare() or wpdb::_real_escape() next.
*/ */
public function esc_like( $text ) { public function esc_like( $text ) {
return addcslashes( $text, '_%\\' ); return addcslashes( $text, '_%\\' );
} }
/** /**
* Print SQL/DB error. * Prints SQL/DB error.
* *
* @since 0.71 * @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. * @return void|false Void if the showing of errors is enabled, false if disabled.
*/ */
public function print_error( $str = '' ) { public function print_error( $str = '' ) {
@ -1489,15 +1504,14 @@ class wpdb {
/** /**
* Enables showing of database errors. * Enables showing of database errors.
* *
* This function should be used only to enable showing of errors. wpdb::hide_errors() should be used instead for * This function should be used only to enable showing of errors.
* hiding of errors. However, this function can be used to enable and disable showing of database errors. * wpdb::hide_errors() should be used instead for hiding errors.
*
* @see wpdb::hide_errors()
* *
* @since 0.71 * @since 0.71
*
* @see wpdb::hide_errors() * @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. * @return bool Whether showing of errors was previously active.
*/ */
public function show_errors( $show = true ) { public function show_errors( $show = true ) {
@ -1512,6 +1526,7 @@ class wpdb {
* By default database errors are not shown. * By default database errors are not shown.
* *
* @since 0.71 * @since 0.71
*
* @see wpdb::show_errors() * @see wpdb::show_errors()
* *
* @return bool Whether showing of errors was previously active. * @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 * @since 2.5.0
*
* @see wpdb::hide_errors() * @see wpdb::hide_errors()
* *
* @param bool $suppress Optional. New value. Defaults to true. * @param bool $suppress Optional. Whether to suppress errors. Default true.
* @return bool Old value * @return bool Whether suppressing of errors was previously active.
*/ */
public function suppress_errors( $suppress = true ) { public function suppress_errors( $suppress = true ) {
$errors = $this->suppress_errors; $errors = $this->suppress_errors;
@ -1540,7 +1556,7 @@ class wpdb {
} }
/** /**
* Kill cached query results. * Kills cached query results.
* *
* @since 0.71 * @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. * 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 * If using the `mysqlnd` library, the IPv6 address needs to be enclosed
* enclosed in square brackets, whereas it doesn't while using the * in square brackets, whereas it doesn't while using the `libmysqlclient` library.
* `libmysqlclient` library.
* @see https://bugs.php.net/bug.php?id=67563 * @see https://bugs.php.net/bug.php?id=67563
*/ */
if ( $is_ipv6 && extension_loaded( 'mysqlnd' ) ) { 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 * mysqli_real_connect() doesn't support the host param including a port or socket
* duplicates how mysql_connect detects a port and/or socket file. * like mysql_connect() does. This duplicates how mysql_connect() detects a port
* and/or socket file.
* *
* @since 4.9.0 * @since 4.9.0
* *
* @param string $host The DB_HOST setting to parse. * @param string $host The DB_HOST setting to parse.
* @return array|bool Array containing the host, the port, the socket and whether * @return array|false Array containing the host, the port, the socket and
* it is an IPv6 address, in that order. If $host couldn't be parsed, * whether it is an IPv6 address, in that order.
* returns false. * False if $host couldn't be parsed.
*/ */
public function parse_db_host( $host ) { public function parse_db_host( $host ) {
$port = null; $port = null;
@ -1762,8 +1778,8 @@ class wpdb {
/** /**
* Checks that the connection to the database is still up. If not, try to reconnect. * 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 * If this function is unable to reconnect, it will forcibly die, or if called
* has been fired, return false instead. * 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. * 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++ ) { for ( $tries = 1; $tries <= $this->reconnect_retries; $tries++ ) {
// On the last try, re-enable warnings. We want to see a single instance of the // On the last try, re-enable warnings. We want to see a single instance
// "unable to connect" message on the bail() screen, if it appears. // of the "unable to connect" message on the bail() screen, if it appears.
if ( $this->reconnect_retries === $tries && WP_DEBUG ) { if ( $this->reconnect_retries === $tries && WP_DEBUG ) {
error_reporting( $error_reporting ); error_reporting( $error_reporting );
} }
@ -1843,18 +1859,21 @@ class wpdb {
// We weren't able to reconnect, so we better bail. // We weren't able to reconnect, so we better bail.
$this->bail( $message, 'db_connect_fail' ); $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(); 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 * @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 * @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. * 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; $this->num_rows = $num_rows;
$return_val = $num_rows; $return_val = $num_rows;
} }
@ -2033,10 +2052,9 @@ class wpdb {
* *
* @param string $query The query's SQL. * @param string $query The query's SQL.
* @param float $query_time Total time spent on the query, in seconds. * @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 float $query_start Unix timestamp of the time at the start of the query.
* @param array $query_data Custom query data. * @param array $query_data Custom query data.
* }
*/ */
public function log_query( $query, $query_time, $query_callstack, $query_start, $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 array $query_data Custom query data.
* @param string $query The query's SQL. * @param string $query The query's SQL.
* @param float $query_time Total time spent on the query, in seconds. * @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 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 ); $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: * Examples:
* wpdb::insert( 'table', array( 'column' => 'foo', 'field' => 'bar' ) ) * wpdb::insert( 'table', array( 'column' => 'foo', 'field' => 'bar' ) )
* wpdb::insert( 'table', array( 'column' => 'foo', 'field' => 1337 ), array( '%s', '%d' ) ) * wpdb::insert( 'table', array( 'column' => 'foo', 'field' => 1337 ), array( '%s', '%d' ) )
* *
* @since 2.5.0 * @since 2.5.0
*
* @see wpdb::prepare() * @see wpdb::prepare()
* @see wpdb::$field_types * @see wpdb::$field_types
* @see wp_set_wpdb_vars() * @see wp_set_wpdb_vars()
@ -2152,13 +2171,14 @@ class wpdb {
} }
/** /**
* Replace a row into a table. * Replaces a row in the table.
* *
* Examples: * Examples:
* wpdb::replace( 'table', array( 'column' => 'foo', 'field' => 'bar' ) ) * wpdb::replace( 'table', array( 'column' => 'foo', 'field' => 'bar' ) )
* wpdb::replace( 'table', array( 'column' => 'foo', 'field' => 1337 ), array( '%s', '%d' ) ) * wpdb::replace( 'table', array( 'column' => 'foo', 'field' => 1337 ), array( '%s', '%d' ) )
* *
* @since 3.0.0 * @since 3.0.0
*
* @see wpdb::prepare() * @see wpdb::prepare()
* @see wpdb::$field_types * @see wpdb::$field_types
* @see wp_set_wpdb_vars() * @see wp_set_wpdb_vars()
@ -2185,11 +2205,12 @@ class wpdb {
* Runs an insert or replace query based on $type argument. * Runs an insert or replace query based on $type argument.
* *
* @since 3.0.0 * @since 3.0.0
*
* @see wpdb::prepare() * @see wpdb::prepare()
* @see wpdb::$field_types * @see wpdb::$field_types
* @see wp_set_wpdb_vars() * @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). * @param array $data Data to insert (in column => value pairs).
* Both $data columns and $data values should be "raw" (neither should be SQL escaped). * 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 * 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). * A format is one of '%d', '%f', '%s' (integer, float, string).
* If omitted, all values in $data will be treated as strings unless otherwise * If omitted, all values in $data will be treated as strings unless otherwise
* specified in wpdb::$field_types. * 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. * @return int|false The number of rows affected, or false on error.
*/ */
function _insert_replace_helper( $table, $data, $format = null, $type = 'INSERT' ) { 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: * Examples:
* wpdb::update( 'table', array( 'column' => 'foo', 'field' => 'bar' ), array( 'ID' => 1 ) ) * 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' ) ) * wpdb::update( 'table', array( 'column' => 'foo', 'field' => 1337 ), array( 'ID' => 1 ), array( '%s', '%d' ), array( '%d' ) )
* *
* @since 2.5.0 * @since 2.5.0
*
* @see wpdb::prepare() * @see wpdb::prepare()
* @see wpdb::$field_types * @see wpdb::$field_types
* @see wp_set_wpdb_vars() * @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). * @param array $data Data to update (in column => value pairs).
* Both $data columns and $data values should be "raw" (neither should be SQL escaped). * 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 * 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 ) )
* wpdb::delete( 'table', array( 'ID' => 1 ), array( '%d' ) ) * wpdb::delete( 'table', array( 'ID' => 1 ), array( '%d' ) )
* *
* @since 3.4.0 * @since 3.4.0
*
* @see wpdb::prepare() * @see wpdb::prepare()
* @see wpdb::$field_types * @see wpdb::$field_types
* @see wp_set_wpdb_vars() * @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). * @param array $where A named array of WHERE clauses (in column => value pairs).
* Multiple clauses will be joined with ANDs. * Multiple clauses will be joined with ANDs.
* Both $where columns and $where values should be "raw". * Both $where columns and $where values should be "raw".
@ -2370,19 +2395,19 @@ class wpdb {
/** /**
* Processes arrays of field/value pairs and field formats. * 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 * This is a helper method for wpdb's CRUD methods, which take field/value pairs
* clauses. This method first pairs each value with a format. Then it determines the charset of that field, using * for inserts, updates, and where clauses. This method first pairs each value
* that to determine if any invalid text would be stripped. If text is stripped, then field processing is rejected * with a format. Then it determines the charset of that field, using that
* and the query fails. * 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 * @since 4.2.0
* *
* @param string $table Table name. * @param string $table Table name.
* @param array $data Field/value pair. * @param array $data Field/value pair.
* @param mixed $format Format for each field. * @param mixed $format Format for each field.
* * @return array|false An array of fields that contain paired value and formats.
* @return array|false Returns an array of fields that contain paired value and formats. Returns false for * False for invalid values.
* invalid values.
*/ */
protected function process_fields( $table, $data, $format ) { protected function process_fields( $table, $data, $format ) {
$data = $this->process_field_formats( $data, $format ); $data = $this->process_field_formats( $data, $format );
@ -2416,7 +2441,8 @@ class wpdb {
* *
* @param array $data Array of fields to values. * @param array $data Array of fields to values.
* @param mixed $format Formats to be mapped to the values in $data. * @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 ) { protected function process_field_formats( $data, $format ) {
$formats = (array) $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 * @since 4.2.0
* *
* @param array $data As it comes from the wpdb::process_field_formats() method. * @param array $data As it comes from the wpdb::process_field_formats() method.
* @param string $table Table name. * @param string $table Table name.
* @return array|false The same array as $data with additional 'charset' keys. * @return array|false The same array as $data with additional 'charset' keys.
* False on failure.
*/ */
protected function process_field_charsets( $data, $table ) { protected function process_field_charsets( $data, $table ) {
foreach ( $data as $field => $value ) { 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 * @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 * Executes a SQL query and returns the value from the SQL result.
* and/or more than one row, the value in the column and row specified is returned. If $query is null, the value * If the SQL result contains more than one column and/or more than one row,
* in the specified column and row from the previous SQL result is returned. * 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 * @since 0.71
* *
* @param string|null $query Optional. SQL query. Defaults to 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 $x Optional. Column of value to return. Indexed from 0.
* @param int $y Optional. Row 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 ) { public 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)";
@ -2529,28 +2557,28 @@ class wpdb {
$this->query( $query ); $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 ] ) ) { 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. // 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;
} }
/** /**
* Retrieve one row from the database. * Retrieves one row from the database.
* *
* Executes a SQL query and returns the row from the SQL result. * Executes a SQL query and returns the row from the SQL result.
* *
* @since 0.71 * @since 0.71
* *
* @param string|null $query SQL query. * @param string|null $query SQL query.
* @param string $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which * @param string $output Optional. The required return type. Possible values include
* correspond to a stdClass object, an associative array, or a numeric array, * OBJECT, ARRAY_A, or ARRAY_N, which correspond to an stdClass object,
* respectively. Default OBJECT. * an associative array, or a numeric array, respectively. Default OBJECT.
* @param int $y Optional. Row to return. Indexed from 0. * @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 ) { public 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)";
@ -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, * Executes a SQL query and returns the column from the SQL result.
* this function returns the column specified. If $query is null, this function returns the specified column from * If the SQL result contains more than one column, the column specified is returned.
* the previous SQL result. * If $query is null, the specified column from the previous SQL result is returned.
* *
* @since 0.71 * @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. * Executes a SQL query and returns the entire SQL result.
* *
@ -2624,11 +2652,12 @@ class wpdb {
* *
* @param string $query SQL query. * @param string $query SQL query.
* @param string $output Optional. Any of ARRAY_A | ARRAY_N | OBJECT | OBJECT_K constants. * @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 * With one of the first three, return an array of rows indexed
* number. Each row is an associative array (column => value, ...), a numerically indexed * from 0 by SQL result row number. Each row is an associative array
* array (0 => value, ...), or an object. ( ->column = value ), respectively. With * (column => value, ...), a numerically indexed array (0 => value, ...),
* OBJECT_K, return an associative array of row objects keyed by the value of each row's * or an object ( ->column = value ), respectively. With OBJECT_K,
* first column's value. Duplicate keys are discarded. * 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. * @return array|object|null Database query results.
* *
*/ */
@ -2791,8 +2820,8 @@ class wpdb {
* *
* @param string $table Table name. * @param string $table Table name.
* @param string $column Column 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. * @return string|false|WP_Error Column character set as a string. False if the column has
* WP_Error object if there was an error. * no character set. WP_Error object if there was an error.
*/ */
public function get_col_charset( $table, $column ) { public function get_col_charset( $table, $column ) {
$tablekey = strtolower( $table ); $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. * 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 $table Table name.
* @param string $column Column name. * @param string $column Column name.
* @return array|false|WP_Error array( 'length' => (int), 'type' => 'byte' | 'char' ) * @return array|false|WP_Error array( 'length' => (int), 'type' => 'byte' | 'char' ).
* false if the column has no length (for example, numeric column) * False if the column has no length (for example, numeric column).
* WP_Error object if there was an error. * WP_Error object if there was an error.
*/ */
public function get_col_length( $table, $column ) { 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 * The negative regex is faster for non-ASCII strings, as it allows
* a non-ASCII character. * the search to finish as soon as it encounters a non-ASCII character.
* *
* @since 4.2.0 * @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 * @since 4.2.0
* *
@ -3023,11 +3052,12 @@ class wpdb {
* *
* @since 4.2.0 * @since 4.2.0
* *
* @param array $data Array of value arrays. Each value array has the keys 'value' and 'charset'. An optional * @param array $data Array of value arrays. Each value array has the keys 'value' and 'charset'.
* 'ascii' key can be set to false to avoid redundant ASCII checks. * 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 * @return array|WP_Error The $data parameter, with invalid characters removed from each value.
* passthrough: any additional keys such as 'field' are retained in each value array. If we * This works as a passthrough: any additional keys such as 'field' are
* cannot remove invalid characters, a WP_Error object is returned. * retained in each value array. If we cannot remove invalid characters,
* a WP_Error object is returned.
*/ */
protected function strip_invalid_text( $data ) { protected function strip_invalid_text( $data ) {
$db_check_string = false; $db_check_string = false;
@ -3040,8 +3070,8 @@ class wpdb {
$truncate_by_byte_length = 'byte' === $value['length']['type']; $truncate_by_byte_length = 'byte' === $value['length']['type'];
} else { } else {
$length = false; $length = false;
// Since we have no length, we'll never truncate. Initialize the variable to false. true would take us // Since we have no length, we'll never truncate. Initialize the variable to false.
// through an unnecessary (for this case) codepath below. // True would take us through an unnecessary (for this case) codepath below.
$truncate_by_byte_length = false; $truncate_by_byte_length = false;
} }
@ -3180,7 +3210,7 @@ class wpdb {
* *
* @since 4.2.0 * @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. * @return string|WP_Error The converted query, or a WP_Error object if the conversion fails.
*/ */
protected function strip_invalid_text_from_query( $query ) { 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 * @since 4.2.0
* *
@ -3300,9 +3330,10 @@ class wpdb {
/* /*
* SHOW TABLE STATUS LIKE and SHOW TABLES LIKE 'wp\_123\_%' * SHOW TABLE STATUS LIKE and SHOW TABLES LIKE 'wp\_123\_%'
* This quoted LIKE operand seldom holds a full table name. It is usually a * This quoted LIKE operand seldom holds a full table name.
* pattern for matching a prefix so we just strip the trailing % and unescape * It is usually a pattern for matching a prefix so we just
* the _ to get 'wp_123_' which drop-ins can use for routing these SQL statements. * 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 ) ) { 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] ); 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 * @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 * @since 0.71
* *
* @param string $info_type Optional. Type one of name, table, def, max_length, not_null, primary_key, * @param string $info_type Optional. Possible values include 'name', 'table', 'def', 'max_length',
* multiple_key, unique_key, numeric, blob, type, unsigned, zerofill * '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. * @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 * 3: if the col is numeric. 4: col's type. Default -1.
* @return mixed Column Results * @return mixed Column results.
*/ */
public function get_col_info( $info_type = 'name', $col_offset = -1 ) { public function get_col_info( $info_type = 'name', $col_offset = -1 ) {
$this->load_col_info(); $this->load_col_info();
@ -3416,9 +3448,10 @@ class wpdb {
* *
* @since 1.5.0 * @since 1.5.0
* *
* @param string $message The Error message * @param string $message The error message.
* @param string $error_code Optional. A Computer readable string to identify the error. * @param string $error_code Optional. A computer-readable string to identify the error.
* @return false|void * Default '500'.
* @return void|false Void if the showing of errors is enabled, false if disabled.
*/ */
public function bail( $message, $error_code = '500' ) { public function bail( $message, $error_code = '500' ) {
if ( $this->show_errors ) { if ( $this->show_errors ) {
@ -3460,7 +3493,8 @@ class wpdb {
* *
* @since 4.5.0 * @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() { public function close() {
if ( ! $this->dbh ) { 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 * @since 2.5.0
* *
* @global string $wp_version * @global string $wp_version The WordPress version string.
* @global string $required_mysql_version * @global string $required_mysql_version The required MySQL version string.
* @return WP_Error|void * @return void|WP_Error
*/ */
public function check_database_version() { public function check_database_version() {
global $wp_version, $required_mysql_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. * Called when WordPress is generating the table scheme.
* *
@ -3510,7 +3544,7 @@ class wpdb {
* @since 2.5.0 * @since 2.5.0
* @deprecated 3.5.0 Use wpdb::has_cap() * @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() { public function supports_collation() {
_deprecated_function( __FUNCTION__, '3.5.0', 'wpdb::has_cap( \'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 * @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 2.7.0
* @since 4.1.0 Added support for the 'utf8mb4' feature. * @since 4.1.0 Added support for the 'utf8mb4' feature.
@ -3546,8 +3580,8 @@ class wpdb {
* *
* @see wpdb::db_version() * @see wpdb::db_version()
* *
* @param string $db_cap The feature to check for. Accepts 'collation', 'group_concat', 'subqueries', 'set_charset', * @param string $db_cap The feature to check for. Accepts 'collation', 'group_concat',
* 'utf8mb4', or 'utf8mb4_520'. * 'subqueries', 'set_charset', 'utf8mb4', or 'utf8mb4_520'.
* @return int|false Whether the database feature is supported, false otherwise. * @return int|false Whether the database feature is supported, false otherwise.
*/ */
public function has_cap( $db_cap ) { 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 * @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() { public function get_caller() {
return wp_debug_backtrace_summary( __CLASS__ ); return wp_debug_backtrace_summary( __CLASS__ );