From 1a137ef17a7d4e13127ae7df0ed0ae70fbb942aa Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Wed, 29 Dec 2021 23:14:01 +0000 Subject: [PATCH] Docs: Further corrections and improvements to the inline documentation for `wpdb`. See #53399, #54610 Built from https://develop.svn.wordpress.org/trunk@52423 git-svn-id: http://core.svn.wordpress.org/trunk@52015 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-includes/version.php | 2 +- wp-includes/wp-db.php | 91 ++++++++++++++++++++++------------------- 2 files changed, 50 insertions(+), 43 deletions(-) diff --git a/wp-includes/version.php b/wp-includes/version.php index 3bb98e206b..7f51d02ad3 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -16,7 +16,7 @@ * * @global string $wp_version */ -$wp_version = '5.9-beta4-52422'; +$wp_version = '5.9-beta4-52423'; /** * 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 7d819d7d95..a3942735ce 100644 --- a/wp-includes/wp-db.php +++ b/wp-includes/wp-db.php @@ -137,14 +137,15 @@ class wpdb { public $last_result; /** - * MySQL query result. + * Database query result. * * Possible values: * - * - `null` if a query is yet to be made or if the result has since been flushed - * - `mysqli_result` instance when the MySQLi driver is in use, or `resource` when the older - * MySQL driver is in use, for successful SELECT, SHOW, DESCRIBE, or EXPLAIN queries + * - For successful SELECT, SHOW, DESCRIBE, or EXPLAIN queries: + * - `mysqli_result` instance when the `mysqli` driver is in use + * - `resource` when the older `mysql` driver is in use * - `true` for other query types that were successful + * - `null` if a query is yet to be made or if the result has since been flushed * - `false` if the query returned an error * * @since 0.71 @@ -163,16 +164,16 @@ class wpdb { protected $col_meta = array(); /** - * Calculated character sets on tables. + * Calculated character sets keyed by table name. * * @since 4.2.0 * - * @var array + * @var string[] */ protected $table_charset = array(); /** - * Whether text fields in the current query need to be sanity checked. Default false. + * Whether text fields in the current query need to be sanity checked. * * @since 4.2.0 * @@ -208,7 +209,7 @@ class wpdb { * @since 5.3.0 The fifth element in each query log was added to record custom data. * * @var array[] { - * Array of queries that were executed. + * Array of arrays containing information about queries that were executed. * * @type array ...$0 { * Data for each query. @@ -234,7 +235,7 @@ class wpdb { protected $reconnect_retries = 5; /** - * WordPress table prefix + * WordPress table prefix. * * You can set this to have multiple WordPress installations in a single database. * The second reason is for possible security precautions. @@ -282,7 +283,7 @@ class wpdb { public $siteid = 0; /** - * List of WordPress per-blog tables. + * List of WordPress per-site tables. * * @since 2.5.0 * @@ -593,9 +594,9 @@ class wpdb { * * Possible values: * + * - `mysqli` instance when the `mysqli` driver is in use + * - `resource` when the older `mysql` driver is in use * - `null` if the connection is yet to be made or has been closed - * - `mysqli` instance when the MySQLi driver is in use - * - `resource` when the older MySQL driver is in use * - `false` if the connection has failed * * @since 0.71 @@ -684,24 +685,24 @@ class wpdb { /** * Connects to the database server and selects a database. * - * PHP5 style constructor for compatibility with PHP5. Does the actual setting up + * Does the actual setting up * of the class properties and connection to the database. * * @since 2.0.8 * * @link https://core.trac.wordpress.org/ticket/3354 * - * @param string $dbuser MySQL database user. - * @param string $dbpassword MySQL database password. - * @param string $dbname MySQL database name. - * @param string $dbhost MySQL database host. + * @param string $dbuser Database user. + * @param string $dbpassword Database password. + * @param string $dbname Database name. + * @param string $dbhost Database host. */ public function __construct( $dbuser, $dbpassword, $dbname, $dbhost ) { if ( WP_DEBUG && WP_DEBUG_DISPLAY ) { $this->show_errors(); } - // Use ext/mysqli if it exists unless WP_USE_EXT_MYSQL is defined as true. + // Use the `mysqli` extension if it exists unless `WP_USE_EXT_MYSQL` is defined as true. if ( function_exists( 'mysqli_connect' ) ) { $this->use_mysqli = true; @@ -1074,16 +1075,16 @@ 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 + * 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: + * 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 on multisite. - * 'ms_global' - returns the multisite global tables, regardless if current installation is multisite. - * 'old' - returns tables which are deprecated. + * - '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 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 * @@ -1097,7 +1098,7 @@ class wpdb { * @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. + * Defaults to `wpdb::$blogid`. * @return string[] Table names. When a prefix is requested, the key is the unprefixed table name. */ public function tables( $scope = 'all', $prefix = true, $blog_id = 0 ) { @@ -1163,7 +1164,7 @@ class wpdb { * * @since 0.71 * - * @param string $db MySQL database name. + * @param string $db Database name. * @param mysqli|resource $dbh Optional database connection. */ public function select( $db, $dbh = null ) { @@ -1350,18 +1351,19 @@ class wpdb { * Prepares a SQL query for safe execution. * * Uses sprintf()-like syntax. The following placeholders can be used in the query string: - * %d (integer) - * %f (float) - * %s (string) + * + * - %d (integer) + * - %f (float) + * - %s (string) * * 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, - * numbered or formatted string placeholders (eg, %1$s, %5s) will not have quotes + * 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 + * 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(). @@ -1370,6 +1372,7 @@ class wpdb { * 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' ); * @@ -1510,7 +1513,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 SQL. * * Use this only before wpdb::prepare() or esc_sql(). Reversing the order is very bad for security. * @@ -1699,7 +1702,7 @@ class wpdb { /** * 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. * * @since 3.0.0 * @since 3.9.0 $allow_bail parameter added. @@ -1898,7 +1901,7 @@ class wpdb { * 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. + * If `$allow_bail` is false, the lack of database connection will need to be handled manually. * * @since 3.9.0 * @@ -1982,7 +1985,7 @@ class wpdb { } /** - * Performs a MySQL database query, using current database connection. + * Performs a database query, using current database connection. * * More information can be found on the documentation page. * @@ -2047,7 +2050,7 @@ class wpdb { $this->_do_query( $query ); - // MySQL server has gone away, try to reconnect. + // Database server has gone away, try to reconnect. $mysql_errno = 0; if ( ! empty( $this->dbh ) ) { if ( $this->use_mysqli ) { @@ -2272,6 +2275,7 @@ class wpdb { * 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' ) ) * @@ -2301,6 +2305,7 @@ class wpdb { * 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' ) ) * @@ -2388,6 +2393,7 @@ class wpdb { * 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' ) ) * @@ -2467,6 +2473,7 @@ class wpdb { * Deletes a row in the table. * * Examples: + * * wpdb::delete( 'table', array( 'ID' => 1 ) ) * wpdb::delete( 'table', array( 'ID' => 1 ), array( '%d' ) ) * @@ -2881,8 +2888,9 @@ class wpdb { * * @since 4.2.0 * - * @param string|null $charset The character set to use. Default null. - * @param string $table The name of the table being checked. + * @param string|WP_Error|null $charset The character set to use, WP_Error object + * if it couldn't be found. Default null. + * @param string $table The name of the table being checked. */ $charset = apply_filters( 'pre_get_table_charset', null, $table ); if ( null !== $charset ) { @@ -3637,7 +3645,6 @@ class wpdb { } } - /** * Closes the current database connection. * @@ -3783,7 +3790,7 @@ class wpdb { } /** - * Retrieves the MySQL server version. + * Retrieves the database server version. * * @since 2.7.0 * @@ -3794,7 +3801,7 @@ class wpdb { } /** - * Retrieves full MySQL server information. + * Retrieves full database server information. * * @since 5.5.0 *