WordPress-C
/
WordPress
mirror of https://github.com/WordPress/WordPress.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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
This commit is contained in:
John Blackbourn 2021-12-29 23:14:01 +00:00
parent 678f2ceb0d
commit 1a137ef17a
2 changed files with 50 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
wp-includes/version.php
View File

@ -16,7 +16,7 @@
* *
* @global string $wp_version * @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. * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.

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

@ -137,14 +137,15 @@ class wpdb {
public $last_result; public $last_result;
/** /**
* MySQL query result. * Database query result.
* *
* Possible values: * Possible values:
* *
* - `null` if a query is yet to be made or if the result has since been flushed * - For successful SELECT, SHOW, DESCRIBE, or EXPLAIN queries:
* - `mysqli_result` instance when the MySQLi driver is in use, or `resource` when the older * - `mysqli_result` instance when the `mysqli` driver is in use
* MySQL driver is in use, for successful SELECT, SHOW, DESCRIBE, or EXPLAIN queries * - `resource` when the older `mysql` driver is in use
* - `true` for other query types that were successful * - `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 * - `false` if the query returned an error
* *
* @since 0.71 * @since 0.71
@ -163,16 +164,16 @@ class wpdb {
protected $col_meta = array(); protected $col_meta = array();
/** /**
* Calculated character sets on tables. * Calculated character sets keyed by table name.
* *
* @since 4.2.0 * @since 4.2.0
* *
* @var array * @var string[]
*/ */
protected $table_charset = array(); 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 * @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. * @since 5.3.0 The fifth element in each query log was added to record custom data.
* *
* @var array[] { * @var array[] {
* Array of queries that were executed. * Array of arrays containing information about queries that were executed.
* *
* @type array ...$0 { * @type array ...$0 {
* Data for each query. * Data for each query.
@ -234,7 +235,7 @@ class wpdb {
protected $reconnect_retries = 5; protected $reconnect_retries = 5;
/** /**
* WordPress table prefix * WordPress table prefix.
* *
* You can set this to have multiple WordPress installations in a single database. * You can set this to have multiple WordPress installations in a single database.
* The second reason is for possible security precautions. * The second reason is for possible security precautions.
@ -282,7 +283,7 @@ class wpdb {
public $siteid = 0; public $siteid = 0;
/** /**
* List of WordPress per-blog tables. * List of WordPress per-site tables.
* *
* @since 2.5.0 * @since 2.5.0
* *
@ -593,9 +594,9 @@ class wpdb {
* *
* Possible values: * 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 * - `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 * - `false` if the connection has failed
* *
* @since 0.71 * @since 0.71
@ -684,24 +685,24 @@ 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 * Does the actual setting up
* of the class properties and connection to the database. * of the class properties and connection to the database.
* *
* @since 2.0.8 * @since 2.0.8
* *
* @link https://core.trac.wordpress.org/ticket/3354 * @link https://core.trac.wordpress.org/ticket/3354
* *
* @param string $dbuser MySQL database user. * @param string $dbuser Database user.
* @param string $dbpassword MySQL database password. * @param string $dbpassword Database password.
* @param string $dbname MySQL database name. * @param string $dbname Database name.
* @param string $dbhost MySQL database host. * @param string $dbhost Database host.
*/ */
public function __construct( $dbuser, $dbpassword, $dbname, $dbhost ) { public function __construct( $dbuser, $dbpassword, $dbname, $dbhost ) {
if ( WP_DEBUG && WP_DEBUG_DISPLAY ) { if ( WP_DEBUG && WP_DEBUG_DISPLAY ) {
$this->show_errors(); $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' ) ) { if ( function_exists( 'mysqli_connect' ) ) {
$this->use_mysqli = true; $this->use_mysqli = true;
@ -1074,16 +1075,16 @@ 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 * 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. * 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 on 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
* *
@ -1097,7 +1098,7 @@ class wpdb {
* @param bool $prefix Optional. Whether to include table prefixes. If blog prefix is requested, * @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. * 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. * @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. * @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 ) { public function tables( $scope = 'all', $prefix = true, $blog_id = 0 ) {
@ -1163,7 +1164,7 @@ class wpdb {
* *
* @since 0.71 * @since 0.71
* *
* @param string $db MySQL database name. * @param string $db Database name.
* @param mysqli|resource $dbh Optional database connection. * @param mysqli|resource $dbh Optional database connection.
*/ */
public function select( $db, $dbh = null ) { public function select( $db, $dbh = null ) {
@ -1350,18 +1351,19 @@ class wpdb {
* Prepares a SQL query for safe execution. * Prepares a SQL query for safe execution.
* *
* Uses sprintf()-like syntax. The following placeholders can be used in the query string: * Uses sprintf()-like syntax. The following placeholders can be used in the query string:
* %d (integer) *
* %f (float) * - %d (integer)
* %s (string) * - %f (float)
* - %s (string)
* *
* All placeholders MUST be left unquoted in the query string. A corresponding argument * All placeholders MUST be left unquoted in the query string. A corresponding argument
* MUST be passed for each placeholder. * MUST be passed for each placeholder.
* *
* Note: There is one exception to the above: for compatibility with old behavior, * 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. * 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 * (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. * the complete LIKE string, these cannot be inserted directly in the query string.
* Also see wpdb::esc_like(). * Also see wpdb::esc_like().
@ -1370,6 +1372,7 @@ class wpdb {
* containing all arguments. 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' );
* *
@ -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. * 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. * 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.0.0
* @since 3.9.0 $allow_bail parameter added. * @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 * 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. * 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 * @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. * More information can be found on the documentation page.
* *
@ -2047,7 +2050,7 @@ class wpdb {
$this->_do_query( $query ); $this->_do_query( $query );
// MySQL server has gone away, try to reconnect. // Database server has gone away, try to reconnect.
$mysql_errno = 0; $mysql_errno = 0;
if ( ! empty( $this->dbh ) ) { if ( ! empty( $this->dbh ) ) {
if ( $this->use_mysqli ) { if ( $this->use_mysqli ) {
@ -2272,6 +2275,7 @@ class wpdb {
* Inserts a row into the 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' ) )
* *
@ -2301,6 +2305,7 @@ class wpdb {
* Replaces a row in the 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' ) )
* *
@ -2388,6 +2393,7 @@ class wpdb {
* Updates 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' ) )
* *
@ -2467,6 +2473,7 @@ class wpdb {
* Deletes a row in the table. * Deletes a row in the table.
* *
* Examples: * 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' ) )
* *
@ -2881,8 +2888,9 @@ class wpdb {
* *
* @since 4.2.0 * @since 4.2.0
* *
* @param string|null $charset The character set to use. Default null. * @param string|WP_Error|null $charset The character set to use, WP_Error object
* @param string $table The name of the table being checked. * 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 ); $charset = apply_filters( 'pre_get_table_charset', null, $table );
if ( null !== $charset ) { if ( null !== $charset ) {
@ -3637,7 +3645,6 @@ class wpdb {
} }
} }
/** /**
* Closes the current database connection. * 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 * @since 2.7.0
* *
@ -3794,7 +3801,7 @@ class wpdb {
} }
/** /**
* Retrieves full MySQL server information. * Retrieves full database server information.
* *
* @since 5.5.0 * @since 5.5.0
* *