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
*/
$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.

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

@ -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
*