WordPress.org
Get WordPress

Make WordPress Core

Changeset 52423


Ignore:
Timestamp:
12/29/2021 11:12:28 PM (3 years ago)
Author:
johnbillion
Message:

Docs: Further corrections and improvements to the inline documentation for wpdb.

See #53399, #54610

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-includes/wp-db.php

    r52422 r52423  
    138138
    139139    /**
    140      * MySQL query result.
     140     * Database query result.
    141141     *
    142142     * Possible values:
    143143     *
     144     * - For successful SELECT, SHOW, DESCRIBE, or EXPLAIN queries:
     145     *   - `mysqli_result` instance when the `mysqli` driver is in use
     146     *   - `resource` when the older `mysql` driver is in use
     147     * - `true` for other query types that were successful
    144148     * - `null` if a query is yet to be made or if the result has since been flushed
    145      * - `mysqli_result` instance when the MySQLi driver is in use, or `resource` when the older
    146      *   MySQL driver is in use, for successful SELECT, SHOW, DESCRIBE, or EXPLAIN queries
    147      * - `true` for other query types that were successful
    148149     * - `false` if the query returned an error
    149150     *
    … …  
    164165
    165166    /**
    166      * Calculated character sets on tables.
     167     * Calculated character sets keyed by table name.
    167168     *
    168169     * @since 4.2.0
    169170     *
    170      * @var array
     171     * @var string[]
    171172     */
    172173    protected $table_charset = array();
    173174
    174175    /**
    175      * Whether text fields in the current query need to be sanity checked. Default false.
     176     * Whether text fields in the current query need to be sanity checked.
    176177     *
    177178     * @since 4.2.0
    … …  
    209210     *
    210211     * @var array[] {
    211      *     Array of queries that were executed.
     212     *     Array of arrays containing information about queries that were executed.
    212213     *
    213214     *     @type array ...$0 {
    … …  
    235236
    236237    /**
    237      * WordPress table prefix
     238     * WordPress table prefix.
    238239     *
    239240     * You can set this to have multiple WordPress installations in a single database.
    … …  
    283284
    284285    /**
    285      * List of WordPress per-blog tables.
     286     * List of WordPress per-site tables.
    286287     *
    287288     * @since 2.5.0
    … …  
    594595     * Possible values:
    595596     *
     597     * - `mysqli` instance when the `mysqli` driver is in use
     598     * - `resource` when the older `mysql` driver is in use
    596599     * - `null` if the connection is yet to be made or has been closed
    597      * - `mysqli` instance when the MySQLi driver is in use
    598      * - `resource` when the older MySQL driver is in use
    599600     * - `false` if the connection has failed
    600601     *
    … …  
    685686     * Connects to the database server and selects a database.
    686687     *
    687      * PHP5 style constructor for compatibility with PHP5. Does the actual setting up
     688     * Does the actual setting up
    688689     * of the class properties and connection to the database.
    689690     *
    … …  
    692693     * @link https://core.trac.wordpress.org/ticket/3354
    693694     *
    694      * @param string $dbuser     MySQL database user.
    695      * @param string $dbpassword MySQL database password.
    696      * @param string $dbname     MySQL database name.
    697      * @param string $dbhost     MySQL database host.
     695     * @param string $dbuser     Database user.
     696     * @param string $dbpassword Database password.
     697     * @param string $dbname     Database name.
     698     * @param string $dbhost     Database host.
    698699     */
    699700    public function __construct( $dbuser, $dbpassword, $dbname, $dbhost ) {
    … …  
    702703        }
    703704
    704         // Use ext/mysqli if it exists unless WP_USE_EXT_MYSQL is defined as true.
     705        // Use the `mysqli` extension if it exists unless `WP_USE_EXT_MYSQL` is defined as true.
    705706        if ( function_exists( 'mysqli_connect' ) ) {
    706707            $this->use_mysqli = true;
    … …  
    10751076     * Returns an array of WordPress tables.
    10761077     *
    1077      * Also allows for the CUSTOM_USER_TABLE and CUSTOM_USER_META_TABLE to override the WordPress users
     1078     * Also allows for the `CUSTOM_USER_TABLE` and `CUSTOM_USER_META_TABLE` to override the WordPress users
    10781079     * and usermeta tables that would otherwise be determined by the prefix.
    10791080     *
    1080      * The $scope argument can take one of the following:
    1081      *
    1082      * 'all' - returns 'all' and 'global' tables. No old tables are returned.
    1083      * 'blog' - returns the blog-level tables for the queried blog.
    1084      * 'global' - returns the global tables for the installation, returning multisite tables only on multisite.
    1085      * 'ms_global' - returns the multisite global tables, regardless if current installation is multisite.
    1086      * 'old' - returns tables which are deprecated.
     1081     * The `$scope` argument can take one of the following:
     1082     *
     1083     * - 'all' - returns 'all' and 'global' tables. No old tables are returned.
     1084     * - 'blog' - returns the blog-level tables for the queried blog.
     1085     * - 'global' - returns the global tables for the installation, returning multisite tables only on multisite.
     1086     * - 'ms_global' - returns the multisite global tables, regardless if current installation is multisite.
     1087     * - 'old' - returns tables which are deprecated.
    10871088     *
    10881089     * @since 3.0.0
    … …  
    10981099     *                        then the custom users and usermeta tables will be mapped. Default true.
    10991100     * @param int    $blog_id Optional. The blog_id to prefix. Used only when prefix is requested.
    1100      *                        Defaults to wpdb::$blogid.
     1101     *                        Defaults to `wpdb::$blogid`.
    11011102     * @return string[] Table names. When a prefix is requested, the key is the unprefixed table name.
    11021103     */
    … …  
    11641165     * @since 0.71
    11651166     *
    1166      * @param string          $db  MySQL database name.
     1167     * @param string          $db  Database name.
    11671168     * @param mysqli|resource $dbh Optional database connection.
    11681169     */
    … …  
    13511352     *
    13521353     * Uses sprintf()-like syntax. The following placeholders can be used in the query string:
    1353      *   %d (integer)
    1354      *   %f (float)
    1355      *   %s (string)
     1354     *
     1355     * - %d (integer)
     1356     * - %f (float)
     1357     * - %s (string)
    13561358     *
    13571359     * All placeholders MUST be left unquoted in the query string. A corresponding argument
    … …  
    13591361     *
    13601362     * Note: There is one exception to the above: for compatibility with old behavior,
    1361      * numbered or formatted string placeholders (eg, %1$s, %5s) will not have quotes
     1363     * numbered or formatted string placeholders (eg, `%1$s`, `%5s`) will not have quotes
    13621364     * added by this function, so should be passed with appropriate quotes around them.
    13631365     *
    1364      * Literal percentage signs (%) in the query string must be written as %%. Percentage wildcards
     1366     * Literal percentage signs (`%`) in the query string must be written as `%%`. Percentage wildcards
    13651367     * (for example, to use in LIKE syntax) must be passed via a substitution argument containing
    13661368     * the complete LIKE string, these cannot be inserted directly in the query string.
    … …  
    13711373     *
    13721374     * Examples:
     1375     *
    13731376     *     $wpdb->prepare( "SELECT * FROM `table` WHERE `column` = %s AND `field` = %d OR `other_field` LIKE %s", array( 'foo', 1337, '%bar' ) );
    13741377     *     $wpdb->prepare( "SELECT DATE_FORMAT(`field`, '%%c') FROM `table` WHERE `column` = %s", 'foo' );
    … …  
    15111514
    15121515    /**
    1513      * First half of escaping for LIKE special characters % and _ before preparing for MySQL.
     1516     * First half of escaping for `LIKE` special characters `%` and `_` before preparing for SQL.
    15141517     *
    15151518     * Use this only before wpdb::prepare() or esc_sql(). Reversing the order is very bad for security.
    … …  
    17001703     * Connects to and selects database.
    17011704     *
    1702      * If $allow_bail is false, the lack of database connection will need to be handled manually.
     1705     * If `$allow_bail` is false, the lack of database connection will need to be handled manually.
    17031706     *
    17041707     * @since 3.0.0
    … …  
    18991902     * after the {@see 'template_redirect'} hook has been fired, return false instead.
    19001903     *
    1901      * If $allow_bail is false, the lack of database connection will need to be handled manually.
     1904     * If `$allow_bail` is false, the lack of database connection will need to be handled manually.
    19021905     *
    19031906     * @since 3.9.0
    … …  
    19831986
    19841987    /**
    1985      * Performs a MySQL database query, using current database connection.
     1988     * Performs a database query, using current database connection.
    19861989     *
    19871990     * More information can be found on the documentation page.
    … …  
    20482051        $this->_do_query( $query );
    20492052
    2050         // MySQL server has gone away, try to reconnect.
     2053        // Database server has gone away, try to reconnect.
    20512054        $mysql_errno = 0;
    20522055        if ( ! empty( $this->dbh ) ) {
    … …  
    22732276     *
    22742277     * Examples:
     2278     *
    22752279     *     wpdb::insert( 'table', array( 'column' => 'foo', 'field' => 'bar' ) )
    22762280     *     wpdb::insert( 'table', array( 'column' => 'foo', 'field' => 1337 ), array( '%s', '%d' ) )
    … …  
    23022306     *
    23032307     * Examples:
     2308     *
    23042309     *     wpdb::replace( 'table', array( 'column' => 'foo', 'field' => 'bar' ) )
    23052310     *     wpdb::replace( 'table', array( 'column' => 'foo', 'field' => 1337 ), array( '%s', '%d' ) )
    … …  
    23892394     *
    23902395     * Examples:
     2396     *
    23912397     *     wpdb::update( 'table', array( 'column' => 'foo', 'field' => 'bar' ), array( 'ID' => 1 ) )
    23922398     *     wpdb::update( 'table', array( 'column' => 'foo', 'field' => 1337 ), array( 'ID' => 1 ), array( '%s', '%d' ), array( '%d' ) )
    … …  
    24682474     *
    24692475     * Examples:
     2476     *
    24702477     *     wpdb::delete( 'table', array( 'ID' => 1 ) )
    24712478     *     wpdb::delete( 'table', array( 'ID' => 1 ), array( '%d' ) )
    … …  
    28822889         * @since 4.2.0
    28832890         *
    2884          * @param string|null $charset The character set to use. Default null.
    2885          * @param string      $table   The name of the table being checked.
     2891         * @param string|WP_Error|null $charset The character set to use, WP_Error object
     2892         *                                      if it couldn't be found. Default null.
     2893         * @param string               $table   The name of the table being checked.
    28862894         */
    28872895        $charset = apply_filters( 'pre_get_table_charset', null, $table );
    … …  
    36383646    }
    36393647
    3640 
    36413648    /**
    36423649     * Closes the current database connection.
    … …  
    37843791
    37853792    /**
    3786      * Retrieves the MySQL server version.
     3793     * Retrieves the database server version.
    37873794     *
    37883795     * @since 2.7.0
    … …  
    37953802
    37963803    /**
    3797      * Retrieves full MySQL server information.
     3804     * Retrieves full database server information.
    37983805     *
    37993806     * @since 5.5.0
Note: See TracChangeset for help on using the changeset viewer.