From 72ef4ae81a56eaad779df879574fea8b93b62e1e Mon Sep 17 00:00:00 2001 From: Sergey Biryukov Date: Sun, 3 May 2020 11:45:06 +0000 Subject: [PATCH] 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. Built from https://develop.svn.wordpress.org/trunk@47749 git-svn-id: http://core.svn.wordpress.org/trunk@47525 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-includes/version.php | 2 +- wp-includes/wp-db.php | 391 ++++++++++++++++++++++------------------ 2 files changed, 214 insertions(+), 179 deletions(-) diff --git a/wp-includes/version.php b/wp-includes/version.php index bd26d6feb7..649ab8d45a 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -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. diff --git a/wp-includes/wp-db.php b/wp-includes/wp-db.php index 8d425db633..76e93ad81d 100644 --- a/wp-includes/wp-db.php +++ b/wp-includes/wp-db.php @@ -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__ );