WordPress.org
Get WordPress

Make WordPress Core

Changeset 47749


Ignore:
Timestamp:
05/03/2020 11:43:14 AM (4 years ago)
Author:
SergeyBiryukov
Message:

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.

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r47740 r47749  
    3838
    3939/**
    40  * WordPress database access abstraction class
     40 * WordPress database access abstraction class.
    4141 *
    42  * This class is used to interact with a database without needing to use raw SQL statements. By default, WordPress
    43  * uses this class to instantiate the global $wpdb object, providing access to the WordPress database.
     42 * This class is used to interact with a database without needing to use raw SQL statements.
     43 * By default, WordPress uses this class to instantiate the global $wpdb object, providing
     44 * access to the WordPress database.
     45 *
     46 * It is possible to replace this class with your own by setting the $wpdb global variable
     47 * in wp-content/db.php file to your class. The wpdb class will still be included, so you can
     48 * extend it or simply use your own.
    4449 *
    4550 * @link https://developer.wordpress.org/reference/classes/wpdb/
    … …  
    6873
    6974    /**
    70      * The last error encountered during the last query.
     75     * The error encountered during the last query.
    7176     *
    7277     * @since 2.5.0
    … …  
    188193     *         @type string $0 The query's SQL.
    189194     *         @type float  $1 Total time spent on the query, in seconds.
    190      *         @type string $2 Comma separated list of the calling functions.
     195     *         @type string $2 Comma-separated list of the calling functions.
    191196     *         @type float  $3 Unix timestamp of the time at the start of the query.
    192197     *         @type array  $4 Custom query data.
    … …  
    271276     * List of deprecated WordPress tables.
    272277     *
    273      * categories, post2cat, and link2cat were deprecated in 2.3.0, db version 5539.
     278     * 'categories', 'post2cat', and 'link2cat' were deprecated in 2.3.0, db version 5539.
    274279     *
    275280     * @since 2.9.0
    … …  
    462467
    463468    /**
    464      * Format specifiers for DB columns. Columns not listed here default to %s. Initialized during WP load.
    465      *
    466      * Keys are column names, values are format types: 'ID' => '%d'
     469     * Format specifiers for DB columns.
     470     *
     471     * Columns not listed here default to %s. Initialized during WP load.
     472     * Keys are column names, values are format types: 'ID' => '%d'.
    467473     *
    468474     * @since 2.8.0
    … …  
    543549     * Whether MySQL is used as the database engine.
    544550     *
    545      * Set in WPDB::db_connect() to true, by default. This is used when checking
     551     * Set in wpdb::db_connect() to true, by default. This is used when checking
    546552     * against the required MySQL version for WordPress. Normally, a replacement
    547553     * database drop-in (db.php) will skip these checks, but setting this to true
    … …  
    587593     * Connects to the database server and selects a database.
    588594     *
    589      * PHP5 style constructor for compatibility with PHP5. Does the actual setting up of the class properties and
    590      * connection to the database.
     595     * PHP5 style constructor for compatibility with PHP5. Does the actual setting up
     596     * of the class properties and connection to the database.
     597     *
     598     * @since 2.0.8
    591599     *
    592600     * @link https://core.trac.wordpress.org/ticket/3354
    593      * @since 2.0.8
    594      *
    595601     * @global string $wp_version The WordPress version string.
    596602     *
    … …  
    633639     *
    634640     * @param string $name The private member to get, and optionally process.
    635      * @return mixed       The private member.
     641     * @return mixed The private member.
    636642     */
    637643    public function __get( $name ) {
    … …  
    668674     * @since 3.5.0
    669675     *
    670      * @param string $name  The private member to check.
    671      *
    672      * @return bool         If the member is set or not.
     676     * @param string $name The private member to check.
     677     * @return bool If the member is set or not.
    673678     */
    674679    public function __isset( $name ) {
    … …  
    688693
    689694    /**
    690      * Set $this->charset and $this->collate
     695     * Sets $this->charset and $this->collate.
    691696     *
    692697     * @since 3.1.0
    … …  
    811816
    812817    /**
    813      * Change the current SQL mode, and ensure its WordPress compatibility.
     818     * Changes the current SQL mode, and ensures its WordPress compatibility.
    814819     *
    815820     * If no modes are passed, it will ensure the current MySQL server modes are compatible.
    … …  
    817822     * @since 3.9.0
    818823     *
    819      * @param array $modes Optional. A list of SQL modes to set.
     824     * @param array $modes Optional. A list of SQL modes to set. Default empty array.
    820825     */
    821826    public function set_sql_mode( $modes = array() ) {
    … …  
    880885     *
    881886     * @param string $prefix          Alphanumeric name for the new prefix.
    882      * @param bool   $set_table_names Optional. Whether the table names, e.g. wpdb::$posts, should be updated or not.
     887     * @param bool   $set_table_names Optional. Whether the table names, e.g. wpdb::$posts,
     888     *                                should be updated or not. Default true.
    883889     * @return string|WP_Error Old prefix or WP_Error on error.
    884890     */
    … …  
    953959     *
    954960     * @since 3.0.0
     961     *
    955962     * @param int $blog_id Optional.
    956963     * @return string Blog prefix.
    … …  
    975982     * Returns an array of WordPress tables.
    976983     *
    977      * Also allows for the CUSTOM_USER_TABLE and CUSTOM_USER_META_TABLE to override the WordPress users and usermeta
    978      * tables that would otherwise be determined by the prefix.
     984     * Also allows for the CUSTOM_USER_TABLE and CUSTOM_USER_META_TABLE to override the WordPress users
     985     * and usermeta tables that would otherwise be determined by the prefix.
    979986     *
    980987     * The $scope argument can take one of the following:
    … …  
    982989     * 'all' - returns 'all' and 'global' tables. No old tables are returned.
    983990     * 'blog' - returns the blog-level tables for the queried blog.
    984      * 'global' - returns the global tables for the installation, returning multisite tables only if running multisite.
     991     * 'global' - returns the global tables for the installation, returning multisite tables only on multisite.
    985992     * 'ms_global' - returns the multisite global tables, regardless if current installation is multisite.
    986993     * 'old' - returns tables which are deprecated.
    987994     *
    988995     * @since 3.0.0
     996     *
    989997     * @uses wpdb::$tables
    990998     * @uses wpdb::$old_tables
    … …  
    9921000     * @uses wpdb::$ms_global_tables
    9931001     *
    994      * @param string $scope   Optional. Can be all, global, ms_global, blog, or old tables. Defaults to all.
    995      * @param bool   $prefix  Optional. Whether to include table prefixes. Default true. If blog
    996      *                        prefix is requested, then the custom users and usermeta tables will be mapped.
    997      * @param int    $blog_id Optional. The blog_id to prefix. Defaults to wpdb::$blogid. Used only when prefix is requested.
     1002     * @param string $scope   Optional. Possible values include 'all', 'global', 'ms_global', 'blog',
     1003     *                        or 'old' tables. Default 'all'.
     1004     * @param bool   $prefix  Optional. Whether to include table prefixes. If blog prefix is requested,
     1005     *                        then the custom users and usermeta tables will be mapped. Default true.
     1006     * @param int    $blog_id Optional. The blog_id to prefix. Used only when prefix is requested.
     1007     *                        Defaults to wpdb::$blogid.
    9981008     * @return array Table names. When a prefix is requested, the key is the unprefixed table name.
    9991009     */
    … …  
    10561066     * Selects a database using the current database connection.
    10571067     *
    1058      * The database name will be changed based on the current database connection. On failure, the execution will
    1059      * bail and display a DB error.
     1068     * The database name will be changed based on the current database connection.
     1069     * On failure, the execution will bail and display a DB error.
    10601070     *
    10611071     * @since 0.71
    10621072     *
    1063      * @param string        $db  MySQL database name
     1073     * @param string        $db  MySQL database name.
    10641074     * @param resource|null $dbh Optional link identifier.
    10651075     */
    … …  
    11231133     * @since 2.8.0
    11241134     * @deprecated 3.6.0 Use wpdb::prepare()
    1125      * @see wpdb::prepare
     1135     * @see wpdb::prepare()
    11261136     * @see esc_sql()
    11271137     *
    … …  
    11371147
    11381148    /**
    1139      * Real escape, using mysqli_real_escape_string() or mysql_real_escape_string()
     1149     * Real escape, using mysqli_real_escape_string() or mysql_real_escape_string().
     1150     *
     1151     * @since 2.8.0
    11401152     *
    11411153     * @see mysqli_real_escape_string()
    11421154     * @see mysql_real_escape_string()
    1143      * @since 2.8.0
    11441155     *
    11451156     * @param string $string String to escape.
    … …  
    11681179
    11691180    /**
    1170      * Escape data. Works on arrays.
     1181     * Escapes data. Works on arrays.
     1182     *
     1183     * @since 2.8.0
    11711184     *
    11721185     * @uses wpdb::_real_escape()
    1173      * @since  2.8.0
    11741186     *
    11751187     * @param string|array $data Data to escape.
    … …  
    12021214     * @see esc_sql()
    12031215     *
    1204      * @param mixed $data
    1205      * @return mixed
     1216     * @param string|array $data Data to escape.
     1217     * @return string|array Escaped data, in the same type as supplied.
    12061218     */
    12071219    public function escape( $data ) {
    … …  
    12471259     *   %s (string)
    12481260     *
    1249      * All placeholders MUST be left unquoted in the query string. A corresponding argument MUST be passed for each
    1250      * placeholder.
    1251      *
    1252      * Note: There is one exception to the above: for compatibility with old behavior, older-style numbered or formatted
    1253      * string placeholders (eg, %1$s, %5s) will not have quotes added by this function, so should be passed with
    1254      * appropriate quotes around them.
    1255      *
    1256      * Literal percentage signs (%) in the query string must be written as %%. Percentage wildcards (for example,
    1257      * to use in LIKE syntax) must be passed via a substitution argument containing the complete LIKE string, these
    1258      * cannot be inserted directly in the query string. Also see wpdb::esc_like().
    1259      *
    1260      * Arguments may be passed as individual arguments to the method, or as a single array containing all arguments.
    1261      * A combination of the two is not supported.
     1261     * All placeholders MUST be left unquoted in the query string. A corresponding argument
     1262     * MUST be passed for each placeholder.
     1263     *
     1264     * Note: There is one exception to the above: for compatibility with old behavior,
     1265     * numbered or formatted string placeholders (eg, %1$s, %5s) will not have quotes
     1266     * added by this function, so should be passed with appropriate quotes around them.
     1267     *
     1268     * Literal percentage signs (%) in the query string must be written as %%. Percentage wildcards
     1269     * (for example, to use in LIKE syntax) must be passed via a substitution argument containing
     1270     * the complete LIKE string, these cannot be inserted directly in the query string.
     1271     * Also see wpdb::esc_like().
     1272     *
     1273     * Arguments may be passed as individual arguments to the method, or as a single array
     1274     * containing all arguments. A combination of the two is not supported.
    12621275     *
    12631276     * Examples:
    … …  
    12651278     *     $wpdb->prepare( "SELECT DATE_FORMAT(`field`, '%%c') FROM `table` WHERE `column` = %s", 'foo' );
    12661279     *
    1267      * @link https://www.php.net/sprintf Description of syntax.
    12681280     * @since 2.3.0
    12691281     * @since 5.3.0 Formalized the existing and already documented `...$args` parameter
    … …  
    12711283     *              from `$args` to `...$args`.
    12721284     *
     1285     * @link https://www.php.net/sprintf Description of syntax.
     1286     *
    12731287     * @param string      $query   Query statement with sprintf()-like placeholders.
    1274      * @param array|mixed $args    The array of variables to substitute into the query's placeholders if being called
    1275      *                             with an array of arguments, or the first variable to substitute into the query's
    1276      *                             placeholders if being called with individual arguments.
    1277      * @param mixed       ...$args Further variables to substitute into the query's placeholders if being called with
     1288     * @param array|mixed $args    The array of variables to substitute into the query's placeholders
     1289     *                             if being called with an array of arguments, or the first variable
     1290     *                             to substitute into the query's placeholders if being called with
    12781291     *                             individual arguments.
    1279      *
     1292     * @param mixed       ...$args Further variables to substitute into the query's placeholders
     1293     *                             if being called with individual arguments.
    12801294     * @return string|void Sanitized query string, if there is a query to prepare.
    12811295     */
    … …  
    13891403     * First half of escaping for LIKE special characters % and _ before preparing for MySQL.
    13901404     *
    1391      * Use this only before wpdb::prepare() or esc_sql().  Reversing the order is very bad for security.
     1405     * Use this only before wpdb::prepare() or esc_sql(). Reversing the order is very bad for security.
    13921406     *
    13931407     * Example Prepared Statement:
    … …  
    14041418     * @since 4.0.0
    14051419     *
    1406      * @param string $text The raw text to be escaped. The input typed by the user should have no
    1407      *                     extra or deleted slashes.
    1408      * @return string Text in the form of a LIKE phrase. The output is not SQL safe. Call $wpdb::prepare()
    1409      *                or real_escape next.
     1420     * @param string $text The raw text to be escaped. The input typed by the user
     1421     *                     should have no extra or deleted slashes.
     1422     * @return string Text in the form of a LIKE phrase. The output is not SQL safe.
     1423     *                Call wpdb::prepare() or wpdb::_real_escape() next.
    14101424     */
    14111425    public function esc_like( $text ) {
    … …  
    14141428
    14151429    /**
    1416      * Print SQL/DB error.
     1430     * Prints SQL/DB error.
    14171431     *
    14181432     * @since 0.71
    1419      * @global array $EZSQL_ERROR Stores error information of query and error string
    1420      *
    1421      * @param string $str The error to display
     1433     *
     1434     * @global array $EZSQL_ERROR Stores error information of query and error string.
     1435     *
     1436     * @param string $str The error to display.
    14221437     * @return void|false Void if the showing of errors is enabled, false if disabled.
    14231438     */
    … …  
    14901505     * Enables showing of database errors.
    14911506     *
    1492      * This function should be used only to enable showing of errors. wpdb::hide_errors() should be used instead for
    1493      * hiding of errors. However, this function can be used to enable and disable showing of database errors.
     1507     * This function should be used only to enable showing of errors.
     1508     * wpdb::hide_errors() should be used instead for hiding errors.
     1509     *
     1510     * @since 0.71
    14941511     *
    14951512     * @see wpdb::hide_errors()
    14961513     *
    1497      * @since 0.71
    1498      * @see wpdb::hide_errors()
    1499      *
    1500      * @param bool $show Whether to show or hide errors.
     1514     * @param bool $show Optional. Whether to show errors. Default true.
    15011515     * @return bool Whether showing of errors was previously active.
    15021516     */
    … …  
    15131527     *
    15141528     * @since 0.71
     1529     *
    15151530     * @see wpdb::show_errors()
    15161531     *
    … …  
    15241539
    15251540    /**
    1526      * Whether to suppress database errors.
    1527      *
    1528      * By default database errors are suppressed, with a simple call to this function they can be enabled.
     1541     * Enables or disables suppressing of database errors.
     1542     *
     1543     * By default database errors are suppressed.
    15291544     *
    15301545     * @since 2.5.0
     1546     *
    15311547     * @see wpdb::hide_errors()
    15321548     *
    1533      * @param bool $suppress Optional. New value. Defaults to true.
    1534      * @return bool Old value
     1549     * @param bool $suppress Optional. Whether to suppress errors. Default true.
     1550     * @return bool Whether suppressing of errors was previously active.
    15351551     */
    15361552    public function suppress_errors( $suppress = true ) {
    … …  
    15411557
    15421558    /**
    1543      * Kill cached query results.
     1559     * Kills cached query results.
    15441560     *
    15451561     * @since 0.71
    … …  
    15721588
    15731589    /**
    1574      * Connect to and select database.
     1590     * Connects to and selects database.
    15751591     *
    15761592     * If $allow_bail is false, the lack of database connection will need to be handled manually.
    … …  
    16061622
    16071623            /*
    1608              * If using the `mysqlnd` library, the IPv6 address needs to be
    1609              * enclosed in square brackets, whereas it doesn't while using the
    1610              * `libmysqlclient` library.
     1624             * If using the `mysqlnd` library, the IPv6 address needs to be enclosed
     1625             * in square brackets, whereas it doesn't while using the `libmysqlclient` library.
    16111626             * @see https://bugs.php.net/bug.php?id=67563
    16121627             */
    … …  
    17081723
    17091724    /**
    1710      * Parse the DB_HOST setting to interpret it for mysqli_real_connect.
    1711      *
    1712      * mysqli_real_connect doesn't support the host param including a port or socket like mysql_connect does. This
    1713      * duplicates how mysql_connect detects a port and/or socket file.
     1725     * Parses the DB_HOST setting to interpret it for mysqli_real_connect().
     1726     *
     1727     * mysqli_real_connect() doesn't support the host param including a port or socket
     1728     * like mysql_connect() does. This duplicates how mysql_connect() detects a port
     1729     * and/or socket file.
    17141730     *
    17151731     * @since 4.9.0
    17161732     *
    17171733     * @param string $host The DB_HOST setting to parse.
    1718      * @return array|bool Array containing the host, the port, the socket and whether
    1719      *                    it is an IPv6 address, in that order. If $host couldn't be parsed,
    1720      *                    returns false.
     1734     * @return array|false Array containing the host, the port, the socket and
     1735     *                     whether it is an IPv6 address, in that order.
     1736     *                     False if $host couldn't be parsed.
    17211737     */
    17221738    public function parse_db_host( $host ) {
    … …  
    17631779     * Checks that the connection to the database is still up. If not, try to reconnect.
    17641780     *
    1765      * If this function is unable to reconnect, it will forcibly die, or if after the {@see 'template_redirect'} hook
    1766      * has been fired, return false instead.
     1781     * If this function is unable to reconnect, it will forcibly die, or if called
     1782     * after the {@see 'template_redirect'} hook has been fired, return false instead.
    17671783     *
    17681784     * If $allow_bail is false, the lack of database connection will need to be handled manually.
    … …  
    17931809
    17941810        for ( $tries = 1; $tries <= $this->reconnect_retries; $tries++ ) {
    1795             // On the last try, re-enable warnings. We want to see a single instance of the
    1796             // "unable to connect" message on the bail() screen, if it appears.
     1811            // On the last try, re-enable warnings. We want to see a single instance
     1812            // of the "unable to connect" message on the bail() screen, if it appears.
    17971813            if ( $this->reconnect_retries === $tries && WP_DEBUG ) {
    17981814                error_reporting( $error_reporting );
    … …  
    18441860        $this->bail( $message, 'db_connect_fail' );
    18451861
    1846         // Call dead_db() if bail didn't die, because this database is no more. It has ceased to be (at least temporarily).
     1862        // Call dead_db() if bail didn't die, because this database is no more.
     1863        // It has ceased to be (at least temporarily).
    18471864        dead_db();
    18481865    }
    18491866
    18501867    /**
    1851      * Perform a MySQL database query, using current database connection.
    1852      *
    1853      * More information can be found on the codex page.
     1868     * Performs a MySQL database query, using current database connection.
     1869     *
     1870     * More information can be found on the Codex page.
    18541871     *
    18551872     * @since 0.71
    18561873     *
    1857      * @param string $query Database query
     1874     * @link https://codex.wordpress.org/Function_Reference/wpdb_Class
     1875     *
     1876     * @param string $query Database query.
    18581877     * @return int|bool Boolean true for CREATE, ALTER, TRUNCATE and DROP queries. Number of rows
    18591878     *                  affected/selected for all other queries. Boolean false on error.
    … …  
    19872006            }
    19882007
    1989             // Log number of rows the query returned and return number of rows selected.
     2008            // Log and return the number of rows selected.
    19902009            $this->num_rows = $num_rows;
    19912010            $return_val     = $num_rows;
    … …  
    20342053     * @param string $query           The query's SQL.
    20352054     * @param float  $query_time      Total time spent on the query, in seconds.
    2036      * @param string $query_callstack Comma separated list of the calling functions.
     2055     * @param string $query_callstack Comma-separated list of the calling functions.
    20372056     * @param float  $query_start     Unix timestamp of the time at the start of the query.
    20382057     * @param array  $query_data      Custom query data.
    2039      * }
    20402058     */
    20412059    public function log_query( $query, $query_time, $query_callstack, $query_start, $query_data ) {
    … …  
    20522070         * @param string $query           The query's SQL.
    20532071         * @param float  $query_time      Total time spent on the query, in seconds.
    2054          * @param string $query_callstack Comma separated list of the calling functions.
     2072         * @param string $query_callstack Comma-separated list of the calling functions.
    20552073         * @param float  $query_start     Unix timestamp of the time at the start of the query.
    20562074         */
    … …  
    21252143
    21262144    /**
    2127      * Insert a row into a table.
     2145     * Inserts a row into the table.
    21282146     *
    21292147     * Examples:
    … …  
    21322150     *
    21332151     * @since 2.5.0
     2152     *
    21342153     * @see wpdb::prepare()
    21352154     * @see wpdb::$field_types
    … …  
    21532172
    21542173    /**
    2155      * Replace a row into a table.
     2174     * Replaces a row in the table.
    21562175     *
    21572176     * Examples:
    … …  
    21602179     *
    21612180     * @since 3.0.0
     2181     *
    21622182     * @see wpdb::prepare()
    21632183     * @see wpdb::$field_types
    … …  
    21862206     *
    21872207     * @since 3.0.0
     2208     *
    21882209     * @see wpdb::prepare()
    21892210     * @see wpdb::$field_types
    21902211     * @see wp_set_wpdb_vars()
    21912212     *
    2192      * @param string       $table  Table name
     2213     * @param string       $table  Table name.
    21932214     * @param array        $data   Data to insert (in column => value pairs).
    21942215     *                             Both $data columns and $data values should be "raw" (neither should be SQL escaped).
    … …  
    22002221     *                             If omitted, all values in $data will be treated as strings unless otherwise
    22012222     *                             specified in wpdb::$field_types.
    2202      * @param string $type         Optional. What type of operation is this? INSERT or REPLACE. Defaults to INSERT.
     2223     * @param string $type         Optional. Type of operation. Possible values include 'INSERT' or 'REPLACE'.
     2224     *                             Default 'INSERT'.
    22032225     * @return int|false The number of rows affected, or false on error.
    22042226     */
    … …  
    22372259
    22382260    /**
    2239      * Update a row in the table.
     2261     * Updates a row in the table.
    22402262     *
    22412263     * Examples:
    … …  
    22442266     *
    22452267     * @since 2.5.0
     2268     *
    22462269     * @see wpdb::prepare()
    22472270     * @see wpdb::$field_types
    22482271     * @see wp_set_wpdb_vars()
    22492272     *
    2250      * @param string       $table        Table name
     2273     * @param string       $table        Table name.
    22512274     * @param array        $data         Data to update (in column => value pairs).
    22522275     *                                   Both $data columns and $data values should be "raw" (neither should be SQL escaped).
    … …  
    23152338
    23162339    /**
    2317      * Delete a row in the table
    2318      *
     2340     * Deletes a row in the table.
     2341     *
     2342     * Examples:
    23192343     *     wpdb::delete( 'table', array( 'ID' => 1 ) )
    23202344     *     wpdb::delete( 'table', array( 'ID' => 1 ), array( '%d' ) )
    23212345     *
    23222346     * @since 3.4.0
     2347     *
    23232348     * @see wpdb::prepare()
    23242349     * @see wpdb::$field_types
    23252350     * @see wp_set_wpdb_vars()
    23262351     *
    2327      * @param string       $table        Table name
     2352     * @param string       $table        Table name.
    23282353     * @param array        $where        A named array of WHERE clauses (in column => value pairs).
    23292354     *                                   Multiple clauses will be joined with ANDs.
    … …  
    23712396     * Processes arrays of field/value pairs and field formats.
    23722397     *
    2373      * This is a helper method for wpdb's CRUD methods, which take field/value pairs for inserts, updates, and where
    2374      * clauses. This method first pairs each value with a format. Then it determines the charset of that field, using
    2375      * that to determine if any invalid text would be stripped. If text is stripped, then field processing is rejected
    2376      * and the query fails.
     2398     * This is a helper method for wpdb's CRUD methods, which take field/value pairs
     2399     * for inserts, updates, and where clauses. This method first pairs each value
     2400     * with a format. Then it determines the charset of that field, using that
     2401     * to determine if any invalid text would be stripped. If text is stripped,
     2402     * then field processing is rejected and the query fails.
    23772403     *
    23782404     * @since 4.2.0
    … …  
    23812407     * @param array  $data   Field/value pair.
    23822408     * @param mixed  $format Format for each field.
    2383      *
    2384      * @return array|false Returns an array of fields that contain paired value and formats. Returns false for
    2385      *                     invalid values.
     2409     * @return array|false An array of fields that contain paired value and formats.
     2410     *                     False for invalid values.
    23862411     */
    23872412    protected function process_fields( $table, $data, $format ) {
    … …  
    24172442     * @param array $data   Array of fields to values.
    24182443     * @param mixed $format Formats to be mapped to the values in $data.
    2419      * @return array Array, keyed by field names with values being an array of 'value' and 'format' keys.
     2444     * @return array Array, keyed by field names with values being an array
     2445     *               of 'value' and 'format' keys.
    24202446     */
    24212447    protected function process_field_formats( $data, $format ) {
    … …  
    24452471
    24462472    /**
    2447      * Adds field charsets to field/value/format arrays generated by the wpdb::process_field_formats() method.
     2473     * Adds field charsets to field/value/format arrays generated by wpdb::process_field_formats().
    24482474     *
    24492475     * @since 4.2.0
    … …  
    24522478     * @param string $table Table name.
    24532479     * @return array|false The same array as $data with additional 'charset' keys.
     2480     *                     False on failure.
    24542481     */
    24552482    protected function process_field_charsets( $data, $table ) {
    … …  
    24752502
    24762503    /**
    2477      * For string fields, record the maximum string length that field can safely save.
     2504     * For string fields, records the maximum string length that field can safely save.
    24782505     *
    24792506     * @since 4.2.1
    … …  
    25062533
    25072534    /**
    2508      * Retrieve one variable from the database.
    2509      *
    2510      * Executes a SQL query and returns the value from the SQL result. If the SQL result contains more than one column
    2511      * and/or more than one row, the value in the column and row specified is returned. If $query is null, the value
    2512      * in the specified column and row from the previous SQL result is returned.
     2535     * Retrieves one variable from the database.
     2536     *
     2537     * Executes a SQL query and returns the value from the SQL result.
     2538     * If the SQL result contains more than one column and/or more than one row,
     2539     * the value in the column and row specified is returned. If $query is null,
     2540     * the value in the specified column and row from the previous SQL result is returned.
    25132541     *
    25142542     * @since 0.71
    … …  
    25172545     * @param int         $x     Optional. Column of value to return. Indexed from 0.
    25182546     * @param int         $y     Optional. Row of value to return. Indexed from 0.
    2519      * @return string|null Database query result (as string), or null on failure
     2547     * @return string|null Database query result (as string), or null on failure.
    25202548     */
    25212549    public function get_var( $query = null, $x = 0, $y = 0 ) {
    … …  
    25302558        }
    25312559
    2532         // Extract var out of cached results based x,y vals.
     2560        // Extract var out of cached results based on x,y vals.
    25332561        if ( ! empty( $this->last_result[ $y ] ) ) {
    25342562            $values = array_values( get_object_vars( $this->last_result[ $y ] ) );
    25352563        }
    25362564
    2537         // If there is a value return it else return null.
     2565        // If there is a value return it, else return null.
    25382566        return ( isset( $values[ $x ] ) && '' !== $values[ $x ] ) ? $values[ $x ] : null;
    25392567    }
    25402568
    25412569    /**
    2542      * Retrieve one row from the database.
     2570     * Retrieves one row from the database.
    25432571     *
    25442572     * Executes a SQL query and returns the row from the SQL result.
    … …  
    25472575     *
    25482576     * @param string|null $query  SQL query.
    2549      * @param string      $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which
    2550      *                            correspond to a stdClass object, an associative array, or a numeric array,
    2551      *                            respectively. Default OBJECT.
     2577     * @param string      $output Optional. The required return type. Possible values include
     2578     *                            OBJECT, ARRAY_A, or ARRAY_N, which correspond to an stdClass object,
     2579     *                            an associative array, or a numeric array, respectively. Default OBJECT.
    25522580     * @param int         $y      Optional. Row to return. Indexed from 0.
    2553      * @return array|object|null|void Database query result in format specified by $output or null on failure
     2581     * @return array|object|null|void Database query result in format specified by $output or null on failure.
    25542582     */
    25552583    public function get_row( $query = null, $output = OBJECT, $y = 0 ) {
    … …  
    25852613
    25862614    /**
    2587      * Retrieve one column from the database.
    2588      *
    2589      * Executes a SQL query and returns the column from the SQL result. If the SQL result contains more than one column,
    2590      * this function returns the column specified. If $query is null, this function returns the specified column from
    2591      * the previous SQL result.
     2615     * Retrieves one column from the database.
     2616     *
     2617     * Executes a SQL query and returns the column from the SQL result.
     2618     * If the SQL result contains more than one column, the column specified is returned.
     2619     * If $query is null, the specified column from the previous SQL result is returned.
    25922620     *
    25932621     * @since 0.71
    … …  
    26172645
    26182646    /**
    2619      * Retrieve an entire SQL result set from the database (i.e., many rows)
     2647     * Retrieves an entire SQL result set from the database (i.e., many rows).
    26202648     *
    26212649     * Executes a SQL query and returns the entire SQL result.
    … …  
    26252653     * @param string $query  SQL query.
    26262654     * @param string $output Optional. Any of ARRAY_A | ARRAY_N | OBJECT | OBJECT_K constants.
    2627      *                       With one of the first three, return an array of rows indexed from 0 by SQL result row
    2628      *                       number. Each row is an associative array (column => value, ...), a numerically indexed
    2629      *                       array (0 => value, ...), or an object. ( ->column = value ), respectively. With
    2630      *                       OBJECT_K, return an associative array of row objects keyed by the value of each row's
    2631      *                       first column's value. Duplicate keys are discarded.
     2655     *                       With one of the first three, return an array of rows indexed
     2656     *                       from 0 by SQL result row number. Each row is an associative array
     2657     *                       (column => value, ...), a numerically indexed array (0 => value, ...),
     2658     *                       or an object ( ->column = value ), respectively. With OBJECT_K,
     2659     *                       return an associative array of row objects keyed by the value
     2660     *                       of each row's first column's value. Duplicate keys are discarded.
    26322661     * @return array|object|null Database query results.
    26332662     *
    … …  
    27922821     * @param string $table  Table name.
    27932822     * @param string $column Column name.
    2794      * @return string|false|WP_Error Column character set as a string. False if the column has no character set.
    2795      *                                WP_Error object if there was an error.
     2823     * @return string|false|WP_Error Column character set as a string. False if the column has
     2824     *                               no character set. WP_Error object if there was an error.
    27962825     */
    27972826    public function get_col_charset( $table, $column ) {
    … …  
    28492878
    28502879    /**
    2851      * Retrieve the maximum string length allowed in a given column.
     2880     * Retrieves the maximum string length allowed in a given column.
    28522881     *
    28532882     * The length may either be specified as a byte length or a character length.
    … …  
    28572886     * @param string $table  Table name.
    28582887     * @param string $column Column name.
    2859      * @return array|false|WP_Error array( 'length' => (int), 'type' => 'byte' | 'char' )
    2860      *                              false if the column has no length (for example, numeric column)
     2888     * @return array|false|WP_Error array( 'length' => (int), 'type' => 'byte' | 'char' ).
     2889     *                              False if the column has no length (for example, numeric column).
    28612890     *                              WP_Error object if there was an error.
    28622891     */
    … …  
    29402969
    29412970    /**
    2942      * Check if a string is ASCII.
    2943      *
    2944      * The negative regex is faster for non-ASCII strings, as it allows the search to finish as soon as it encounters
    2945      * a non-ASCII character.
     2971     * Checks if a string is ASCII.
     2972     *
     2973     * The negative regex is faster for non-ASCII strings, as it allows
     2974     * the search to finish as soon as it encounters a non-ASCII character.
    29462975     *
    29472976     * @since 4.2.0
    … …  
    29632992
    29642993    /**
    2965      * Check if the query is accessing a collation considered safe on the current version of MySQL.
     2994     * Checks if the query is accessing a collation considered safe on the current version of MySQL.
    29662995     *
    29672996     * @since 4.2.0
    … …  
    30243053     * @since 4.2.0
    30253054     *
    3026      * @param array $data Array of value arrays. Each value array has the keys 'value' and 'charset'. An optional
    3027      *                    'ascii' key can be set to false to avoid redundant ASCII checks.
    3028      * @return array|WP_Error The $data parameter, with invalid characters removed from each value. This works as a
    3029      *                        passthrough: any additional keys such as 'field' are retained in each value array. If we
    3030      *                        cannot remove invalid characters, a WP_Error object is returned.
     3055     * @param array $data Array of value arrays. Each value array has the keys 'value' and 'charset'.
     3056     *                    An optional 'ascii' key can be set to false to avoid redundant ASCII checks.
     3057     * @return array|WP_Error The $data parameter, with invalid characters removed from each value.
     3058     *                        This works as a passthrough: any additional keys such as 'field' are
     3059     *                        retained in each value array. If we cannot remove invalid characters,
     3060     *                        a WP_Error object is returned.
    30313061     */
    30323062    protected function strip_invalid_text( $data ) {
    … …  
    30413071            } else {
    30423072                $length = false;
    3043                 // Since we have no length, we'll never truncate. Initialize the variable to false. true would take us
    3044                 // through an unnecessary (for this case) codepath below.
     3073                // Since we have no length, we'll never truncate. Initialize the variable to false.
     3074                // True would take us through an unnecessary (for this case) codepath below.
    30453075                $truncate_by_byte_length = false;
    30463076            }
    … …  
    31813211     * @since 4.2.0
    31823212     *
    3183      * @param string $query    Query to convert.
     3213     * @param string $query Query to convert.
    31843214     * @return string|WP_Error The converted query, or a WP_Error object if the conversion fails.
    31853215     */
    … …  
    32623292
    32633293    /**
    3264      * Find the first table name referenced in a query.
     3294     * Finds the first table name referenced in a query.
    32653295     *
    32663296     * @since 4.2.0
    … …  
    33013331        /*
    33023332         * SHOW TABLE STATUS LIKE and SHOW TABLES LIKE 'wp\_123\_%'
    3303          * This quoted LIKE operand seldom holds a full table name. It is usually a
    3304          * pattern for matching a prefix so we just strip the trailing % and unescape
    3305          * the _ to get 'wp_123_' which drop-ins can use for routing these SQL statements.
     3333         * This quoted LIKE operand seldom holds a full table name.
     3334         * It is usually a pattern for matching a prefix so we just
     3335         * strip the trailing % and unescape the _ to get 'wp_123_'
     3336         * which drop-ins can use for routing these SQL statements.
    33063337         */
    33073338        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 ) ) {
    … …  
    33363367
    33373368    /**
    3338      * Load the column metadata from the last query.
     3369     * Loads the column metadata from the last query.
    33393370     *
    33403371     * @since 3.5.0
    … …  
    33593390
    33603391    /**
    3361      * Retrieve column metadata from the last query.
     3392     * Retrieves column metadata from the last query.
    33623393     *
    33633394     * @since 0.71
    33643395     *
    3365      * @param string $info_type Optional. Type one of name, table, def, max_length, not_null, primary_key,
    3366      *                          multiple_key, unique_key, numeric, blob, type, unsigned, zerofill
     3396     * @param string $info_type Optional. Possible values include 'name', 'table', 'def', 'max_length',
     3397     *                          'not_null', 'primary_key', 'multiple_key', 'unique_key', 'numeric',
     3398     *                          'blob', 'type', 'unsigned', 'zerofill'. Default 'name'.
    33673399     * @param int $col_offset   Optional. 0: col name. 1: which table the col's in. 2: col's max length.
    3368      *                          3: if the col is numeric. 4: col's type
    3369      * @return mixed Column Results
     3400     *                          3: if the col is numeric. 4: col's type. Default -1.
     3401     * @return mixed Column results.
    33703402     */
    33713403    public function get_col_info( $info_type = 'name', $col_offset = -1 ) {
    … …  
    34173449     * @since 1.5.0
    34183450     *
    3419      * @param string $message    The Error message
    3420      * @param string $error_code Optional. A Computer readable string to identify the error.
    3421      * @return false|void
     3451     * @param string $message    The error message.
     3452     * @param string $error_code Optional. A computer-readable string to identify the error.
     3453     *                           Default '500'.
     3454     * @return void|false Void if the showing of errors is enabled, false if disabled.
    34223455     */
    34233456    public function bail( $message, $error_code = '500' ) {
    … …  
    34613494     * @since 4.5.0
    34623495     *
    3463      * @return bool True if the connection was successfully closed, false if it wasn't, or if the connection doesn't exist.
     3496     * @return bool True if the connection was successfully closed,
     3497     *              false if it wasn't, or if the connection doesn't exist.
    34643498     */
    34653499    public function close() {
    … …  
    34843518
    34853519    /**
    3486      * Whether MySQL database is at least the required minimum version.
     3520     * Determines whether MySQL database is at least the required minimum version.
    34873521     *
    34883522     * @since 2.5.0
    34893523     *
    3490      * @global string $wp_version
    3491      * @global string $required_mysql_version
    3492      * @return WP_Error|void
     3524     * @global string $wp_version             The WordPress version string.
     3525     * @global string $required_mysql_version The required MySQL version string.
     3526     * @return void|WP_Error
    34933527     */
    34943528    public function check_database_version() {
    … …  
    35023536
    35033537    /**
    3504      * Whether the database supports collation.
     3538     * Determines whether the database supports collation.
    35053539     *
    35063540     * Called when WordPress is generating the table scheme.
    … …  
    35113545     * @deprecated 3.5.0 Use wpdb::has_cap()
    35123546     *
    3513      * @return bool True if collation is supported, false if version does not
     3547     * @return bool True if collation is supported, false if not.
    35143548     */
    35153549    public function supports_collation() {
    … …  
    35193553
    35203554    /**
    3521      * The database character collate.
     3555     * Retrieves the database character collate.
    35223556     *
    35233557     * @since 3.5.0
    … …  
    35393573
    35403574    /**
    3541      * Determine if a database supports a particular feature.
     3575     * Determines if a database supports a particular feature.
    35423576     *
    35433577     * @since 2.7.0
    … …  
    35473581     * @see wpdb::db_version()
    35483582     *
    3549      * @param string $db_cap The feature to check for. Accepts 'collation', 'group_concat', 'subqueries', 'set_charset',
    3550      *                       'utf8mb4', or 'utf8mb4_520'.
     3583     * @param string $db_cap The feature to check for. Accepts 'collation', 'group_concat',
     3584     *                       'subqueries', 'set_charset', 'utf8mb4', or 'utf8mb4_520'.
    35513585     * @return int|false Whether the database feature is supported, false otherwise.
    35523586     */
    … …  
    35893623
    35903624    /**
    3591      * Retrieve the name of the function that called wpdb.
    3592      *
    3593      * Searches up the list of functions until it reaches the one that would most logically had called this method.
     3625     * Retrieves the name of the function that called wpdb.
     3626     *
     3627     * Searches up the list of functions until it reaches the one that would
     3628     * most logically had called this method.
    35943629     *
    35953630     * @since 2.5.0
    35963631     *
    3597      * @return string Comma separated list of the calling functions.
     3632     * @return string Comma-separated list of the calling functions.
    35983633     */
    35993634    public function get_caller() {
Note: See TracChangeset for help on using the changeset viewer.