Make WordPress Core

Changeset 47740


Ignore:
Timestamp:
05/02/2020 05:23:28 PM (5 years ago)
Author:
johnbillion
Message:

Docs: Update inline documentation for the wpdb class.

Props theMikeD

Fixes #49477

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/wp-db.php

    r47550 r47740  
    11<?php
    22/**
    3  * WordPress DB Class
     3 * WordPress database access abstraction class
    44 *
    55 * Original code from {@link http://php.justinvincent.com Justin Vincent (justin@visunet.ie)}
     
    3838
    3939/**
    40  * WordPress Database Access Abstraction Object
     40 * WordPress database access abstraction class
    4141 *
    42  * It is possible to replace this class with your own
    43  * by setting the $wpdb global variable in wp-content/db.php
    44  * file to your class. The wpdb class will still be included,
    45  * so you can extend it or simply use your own.
     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.
    4644 *
    47  * @link https://codex.wordpress.org/Function_Reference/wpdb_Class
     45 * @link https://developer.wordpress.org/reference/classes/wpdb/
    4846 *
    4947 * @since 0.71
     
    5452     * Whether to show SQL/DB errors.
    5553     *
    56      * Default behavior is to show errors if both WP_DEBUG and WP_DEBUG_DISPLAY
    57      * evaluated to true.
     54     * Default is to show errors if both WP_DEBUG and WP_DEBUG_DISPLAY evaluate to true.
    5855     *
    5956     * @since 0.71
     
    6360
    6461    /**
    65      * Whether to suppress errors during the DB bootstrapping.
     62     * Whether to suppress errors during the DB bootstrapping. Default false.
    6663     *
    6764     * @since 2.5.0
     
    7168
    7269    /**
    73      * The last error during query.
     70     * The last error encountered during the last query.
    7471     *
    7572     * @since 2.5.0
     
    7976
    8077    /**
    81      * Amount of queries made
     78     * The number of queries made.
    8279     *
    8380     * @since 1.2.0
     
    8784
    8885    /**
    89      * Count of rows returned by previous query
     86     * Count of rows returned by the last query.
    9087     *
    9188     * @since 0.71
     
    9592
    9693    /**
    97      * Count of affected rows by previous query
     94     * Count of rows affected by the last query.
    9895     *
    9996     * @since 0.71
     
    103100
    104101    /**
    105      * The ID generated for an AUTO_INCREMENT column by the previous query (usually INSERT).
     102     * The ID generated for an AUTO_INCREMENT column by the last query (usually INSERT).
    106103     *
    107104     * @since 0.71
     
    111108
    112109    /**
    113      * Last query made
     110     * The last query made.
    114111     *
    115112     * @since 0.71
     
    119116
    120117    /**
    121      * Results of the last query made
     118     * Results of the last query.
    122119     *
    123120     * @since 0.71
     
    135132
    136133    /**
    137      * Cached column info, for sanity checking data before inserting
     134     * Cached column info, for sanity checking data before inserting.
    138135     *
    139136     * @since 4.2.0
     
    143140
    144141    /**
    145      * Calculated character sets on tables
     142     * Calculated character sets on tables.
    146143     *
    147144     * @since 4.2.0
     
    151148
    152149    /**
    153      * Whether text fields in the current query need to be sanity checked.
     150     * Whether text fields in the current query need to be sanity checked. Default false.
    154151     *
    155152     * @since 4.2.0
     
    168165
    169166    /**
    170      * Saved info on the table column
     167     * Saved info on the table column.
    171168     *
    172169     * @since 0.71
     
    200197
    201198    /**
    202      * The number of times to retry reconnecting before dying.
     199     * The number of times to retry reconnecting before dying. Default 5.
    203200     *
    204201     * @since 3.9.0
     
    211208     * WordPress table prefix
    212209     *
    213      * You can set this to have multiple WordPress installations
    214      * in a single database. The second reason is for possible
    215      * security precautions.
     210     * You can set this to have multiple WordPress installations in a single database.
     211     * The second reason is for possible security precautions.
    216212     *
    217213     * @since 2.5.0
     
    253249
    254250    /**
    255      * List of WordPress per-blog tables
     251     * List of WordPress per-blog tables.
    256252     *
    257253     * @since 2.5.0
     
    273269
    274270    /**
    275      * List of deprecated WordPress tables
    276      *
    277      * categories, post2cat, and link2cat were deprecated in 2.3.0, db version 5539
     271     * List of deprecated WordPress tables.
     272     *
     273     * categories, post2cat, and link2cat were deprecated in 2.3.0, db version 5539.
    278274     *
    279275     * @since 2.9.0
     
    284280
    285281    /**
    286      * List of WordPress global tables
     282     * List of WordPress global tables.
    287283     *
    288284     * @since 3.0.0
     
    293289
    294290    /**
    295      * List of Multisite global tables
     291     * List of Multisite global tables.
    296292     *
    297293     * @since 3.0.0
     
    310306
    311307    /**
    312      * WordPress Comments table
     308     * WordPress Comments table.
    313309     *
    314310     * @since 1.5.0
     
    318314
    319315    /**
    320      * WordPress Comment Metadata table
     316     * WordPress Comment Metadata table.
    321317     *
    322318     * @since 2.9.0
     
    326322
    327323    /**
    328      * WordPress Links table
     324     * WordPress Links table.
    329325     *
    330326     * @since 1.5.0
     
    334330
    335331    /**
    336      * WordPress Options table
     332     * WordPress Options table.
    337333     *
    338334     * @since 1.5.0
     
    342338
    343339    /**
    344      * WordPress Post Metadata table
     340     * WordPress Post Metadata table.
    345341     *
    346342     * @since 1.5.0
     
    350346
    351347    /**
    352      * WordPress Posts table
     348     * WordPress Posts table.
    353349     *
    354350     * @since 1.5.0
     
    358354
    359355    /**
    360      * WordPress Terms table
     356     * WordPress Terms table.
    361357     *
    362358     * @since 2.3.0
     
    366362
    367363    /**
    368      * WordPress Term Relationships table
     364     * WordPress Term Relationships table.
    369365     *
    370366     * @since 2.3.0
     
    374370
    375371    /**
    376      * WordPress Term Taxonomy table
     372     * WordPress Term Taxonomy table.
    377373     *
    378374     * @since 2.3.0
     
    394390
    395391    /**
    396      * WordPress User Metadata table
     392     * WordPress User Metadata table.
    397393     *
    398394     * @since 2.3.0
     
    402398
    403399    /**
    404      * WordPress Users table
     400     * WordPress Users table.
    405401     *
    406402     * @since 1.5.0
     
    410406
    411407    /**
    412      * Multisite Blogs table
     408     * Multisite Blogs table.
    413409     *
    414410     * @since 3.0.0
     
    418414
    419415    /**
    420      * Multisite Blog Metadata table
     416     * Multisite Blog Metadata table.
    421417     *
    422418     * @since 5.1.0
     
    426422
    427423    /**
    428      * Multisite Registration Log table
     424     * Multisite Registration Log table.
    429425     *
    430426     * @since 3.0.0
     
    434430
    435431    /**
    436      * Multisite Signups table
     432     * Multisite Signups table.
    437433     *
    438434     * @since 3.0.0
     
    442438
    443439    /**
    444      * Multisite Sites table
     440     * Multisite Sites table.
    445441     *
    446442     * @since 3.0.0
     
    450446
    451447    /**
    452      * Multisite Sitewide Terms table
     448     * Multisite Sitewide Terms table.
    453449     *
    454450     * @since 3.0.0
     
    458454
    459455    /**
    460      * Multisite Site Metadata table
     456     * Multisite Site Metadata table.
    461457     *
    462458     * @since 3.0.0
     
    481477
    482478    /**
    483      * Database table columns charset
     479     * Database table columns charset.
    484480     *
    485481     * @since 2.2.0
     
    489485
    490486    /**
    491      * Database table columns collate
     487     * Database table columns collate.
    492488     *
    493489     * @since 2.2.0
     
    497493
    498494    /**
    499      * Database Username
     495     * Database Username.
    500496     *
    501497     * @since 2.9.0
     
    505501
    506502    /**
    507      * Database Password
     503     * Database Password.
    508504     *
    509505     * @since 3.1.0
     
    513509
    514510    /**
    515      * Database Name
     511     * Database Name.
    516512     *
    517513     * @since 3.1.0
     
    521517
    522518    /**
    523      * Database Host
     519     * Database Host.
    524520     *
    525521     * @since 3.1.0
     
    529525
    530526    /**
    531      * Database Handle
     527     * Database Handle.
    532528     *
    533529     * @since 0.71
     
    537533
    538534    /**
    539      * A textual description of the last query/get_row/get_var call
     535     * A textual description of the last query/get_row/get_var call.
    540536     *
    541537     * @since 3.0.0
     
    573569
    574570    /**
    575      * Whether to use mysqli over mysql.
     571     * Whether to use mysqli over mysql. Default false.
    576572     *
    577573     * @since 3.9.0
     
    581577
    582578    /**
    583      * Whether we've managed to successfully connect at some point
     579     * Whether we've managed to successfully connect at some point.
    584580     *
    585581     * @since 3.9.0
     
    589585
    590586    /**
    591      * Connects to the database server and selects a database
    592      *
    593      * PHP5 style constructor for compatibility with PHP5. Does
    594      * the actual setting up of the class properties and connection
    595      * to the database.
     587     * Connects to the database server and selects a database.
     588     *
     589     * PHP5 style constructor for compatibility with PHP5. Does the actual setting up of the class properties and
     590     * connection to the database.
    596591     *
    597592     * @link https://core.trac.wordpress.org/ticket/3354
     
    600595     * @global string $wp_version The WordPress version string.
    601596     *
    602      * @param string $dbuser     MySQL database user
    603      * @param string $dbpassword MySQL database password
    604      * @param string $dbname     MySQL database name
    605      * @param string $dbhost     MySQL database host
     597     * @param string $dbuser     MySQL database user.
     598     * @param string $dbpassword MySQL database password.
     599     * @param string $dbname     MySQL database name.
     600     * @param string $dbhost     MySQL database host.
    606601     */
    607602    public function __construct( $dbuser, $dbpassword, $dbname, $dbhost ) {
     
    637632     * @since 3.5.0
    638633     *
    639      * @param string $name The private member to get, and optionally process
    640      * @return mixed The private member
     634     * @param string $name The private member to get, and optionally process.
     635     * @return mixed       The private member.
    641636     */
    642637    public function __get( $name ) {
     
    653648     * @since 3.5.0
    654649     *
    655      * @param string $name  The private member to set
    656      * @param mixed  $value The value to set
     650     * @param string $name  The private member to set.
     651     * @param mixed  $value The value to set.
    657652     */
    658653    public function __set( $name, $value ) {
     
    673668     * @since 3.5.0
    674669     *
    675      * @param string $name  The private member to check
    676      *
    677      * @return bool If the member is set or not
     670     * @param string $name  The private member to check.
     671     *
     672     * @return bool         If the member is set or not.
    678673     */
    679674    public function __isset( $name ) {
     
    774769     * @since 3.1.0
    775770     *
    776      * @param resource $dbh     The resource given by mysql_connect
     771     * @param resource $dbh     The resource given by mysql_connect.
    777772     * @param string   $charset Optional. The character set. Default null.
    778773     * @param string   $collate Optional. The collation. Default null.
     
    818813     * Change the current SQL mode, and ensure its WordPress compatibility.
    819814     *
    820      * If no modes are passed, it will ensure the current MySQL server
    821      * modes are compatible.
     815     * If no modes are passed, it will ensure the current MySQL server modes are compatible.
    822816     *
    823817     * @since 3.9.0
     
    887881     * @param string $prefix          Alphanumeric name for the new prefix.
    888882     * @param bool   $set_table_names Optional. Whether the table names, e.g. wpdb::$posts, should be updated or not.
    889      * @return string|WP_Error Old prefix or WP_Error on error
     883     * @return string|WP_Error Old prefix or WP_Error on error.
    890884     */
    891885    public function set_prefix( $prefix, $set_table_names = true ) {
     
    932926     * @param int $blog_id
    933927     * @param int $network_id Optional.
    934      * @return int previous blog id
     928     * @return int Previous blog id.
    935929     */
    936930    public function set_blog_id( $blog_id, $network_id = 0 ) {
     
    981975     * Returns an array of WordPress tables.
    982976     *
    983      * Also allows for the CUSTOM_USER_TABLE and CUSTOM_USER_META_TABLE to
    984      * override the WordPress users and usermeta tables that would otherwise
    985      * be determined by the prefix.
    986      *
    987      * The scope argument can take one of the following:
     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.
     979     *
     980     * The $scope argument can take one of the following:
    988981     *
    989982     * 'all' - returns 'all' and 'global' tables. No old tables are returned.
     
    10631056     * Selects a database using the current database connection.
    10641057     *
    1065      * The database name will be changed based on the current database
    1066      * connection. On failure, the execution will bail and display an DB error.
     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.
    10671060     *
    10681061     * @since 0.71
     
    11501143     * @since 2.8.0
    11511144     *
    1152      * @param  string $string to escape
    1153      * @return string escaped
     1145     * @param string $string String to escape.
     1146     * @return string Escaped string.
    11541147     */
    11551148    function _real_escape( $string ) {
     
    11781171     *
    11791172     * @uses wpdb::_real_escape()
    1180      * @since 2.8.0
    1181      *
    1182      * @param  string|array $data
    1183      * @return string|array escaped
     1173     * @since  2.8.0
     1174     *
     1175     * @param string|array $data Data to escape.
     1176     * @return string|array Escaped data, in the same type as supplied.
    11841177     */
    11851178    public function _escape( $data ) {
     
    12321225
    12331226    /**
    1234      * Escapes content by reference for insertion into the database, for security
     1227     * Escapes content by reference for insertion into the database, for security.
    12351228     *
    12361229     * @uses wpdb::_real_escape()
     
    12381231     * @since 2.3.0
    12391232     *
    1240      * @param string $string to escape
     1233     * @param string $string String to escape.
    12411234     */
    12421235    public function escape_by_ref( &$string ) {
     
    12471240
    12481241    /**
    1249      * Prepares a SQL query for safe execution. Uses sprintf()-like syntax.
    1250      *
    1251      * The following placeholders can be used in the query string:
     1242     * Prepares a SQL query for safe execution.
     1243     *
     1244     * Uses sprintf()-like syntax. The following placeholders can be used in the query string:
    12521245     *   %d (integer)
    12531246     *   %f (float)
    12541247     *   %s (string)
    12551248     *
    1256      * All placeholders MUST be left unquoted in the query string. A corresponding argument
    1257      * MUST be passed for each placeholder.
    1258      *
    1259      * For compatibility with old behavior, numbered or formatted string placeholders (eg, %1$s, %5s)
    1260      * will not have quotes added by this function, so should be passed with appropriate quotes around
    1261      * them for your usage.
     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.
    12621255     *
    12631256     * Literal percentage signs (%) in the query string must be written as %%. Percentage wildcards (for example,
     
    12651258     * cannot be inserted directly in the query string. Also see wpdb::esc_like().
    12661259     *
    1267      * Arguments may be passed as individual arguments to the method, or as a single array containing
    1268      * all arguments. A combination of the two is not supported.
     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.
    12691262     *
    12701263     * Examples:
     
    12781271     *              from `$args` to `...$args`.
    12791272     *
    1280      * @param string      $query   Query statement with sprintf()-like placeholders
    1281      * @param array|mixed $args    The array of variables to substitute into the query's placeholders
    1282      *                             if being called with an array of arguments, or the first variable
    1283      *                             to substitute into the query's placeholders if being called with
     1273     * @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
    12841278     *                             individual arguments.
    1285      * @param mixed       ...$args Further variables to substitute into the query's placeholders
    1286      *                             if being called with individual arguments.
     1279     *
    12871280     * @return string|void Sanitized query string, if there is a query to prepare.
    12881281     */
     
    14241417     *
    14251418     * @since 0.71
    1426      * @global array $EZSQL_ERROR Stores error information of query and error string.
    1427      *
    1428      * @param string $str The error to display.
     1419     * @global array $EZSQL_ERROR Stores error information of query and error string
     1420     *
     1421     * @param string $str The error to display
    14291422     * @return void|false Void if the showing of errors is enabled, false if disabled.
    14301423     */
     
    14971490     * Enables showing of database errors.
    14981491     *
    1499      * This function should be used only to enable showing of errors.
    1500      * wpdb::hide_errors() should be used instead for hiding of errors. However,
    1501      * this function can be used to enable and disable showing of database
    1502      * errors.
     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.
     1494     *
     1495     * @see wpdb::hide_errors()
    15031496     *
    15041497     * @since 0.71
    15051498     * @see wpdb::hide_errors()
    15061499     *
    1507      * @param bool $show Whether to show or hide errors
    1508      * @return bool Old value for showing errors.
     1500     * @param bool $show Whether to show or hide errors.
     1501     * @return bool Whether showing of errors was previously active.
    15091502     */
    15101503    public function show_errors( $show = true ) {
     
    15221515     * @see wpdb::show_errors()
    15231516     *
    1524      * @return bool Whether showing of errors was active
     1517     * @return bool Whether showing of errors was previously active.
    15251518     */
    15261519    public function hide_errors() {
     
    15331526     * Whether to suppress database errors.
    15341527     *
    1535      * By default database errors are suppressed, with a simple
    1536      * call to this function they can be enabled.
     1528     * By default database errors are suppressed, with a simple call to this function they can be enabled.
    15371529     *
    15381530     * @since 2.5.0
    15391531     * @see wpdb::hide_errors()
     1532     *
    15401533     * @param bool $suppress Optional. New value. Defaults to true.
    15411534     * @return bool Old value
     
    15811574     * Connect to and select database.
    15821575     *
    1583      * If $allow_bail is false, the lack of database connection will need
    1584      * to be handled manually.
     1576     * If $allow_bail is false, the lack of database connection will need to be handled manually.
    15851577     *
    15861578     * @since 3.0.0
     
    17181710     * Parse the DB_HOST setting to interpret it for mysqli_real_connect.
    17191711     *
    1720      * mysqli_real_connect doesn't support the host param including a port or
    1721      * socket like mysql_connect does. This duplicates how mysql_connect detects
    1722      * a port and/or socket file.
     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.
    17231714     *
    17241715     * @since 4.9.0
     
    17721763     * Checks that the connection to the database is still up. If not, try to reconnect.
    17731764     *
    1774      * If this function is unable to reconnect, it will forcibly die, or if after the
    1775      * the {@see 'template_redirect'} hook has been fired, return false instead.
    1776      *
    1777      * If $allow_bail is false, the lack of database connection will need
    1778      * to be handled manually.
     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.
     1767     *
     1768     * If $allow_bail is false, the lack of database connection will need to be handled manually.
    17791769     *
    17801770     * @since 3.9.0
     
    18031793
    18041794        for ( $tries = 1; $tries <= $this->reconnect_retries; $tries++ ) {
    1805             // On the last try, re-enable warnings. We want to see a single instance
    1806             // of the "unable to connect" message on the bail() screen, if it appears.
     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.
    18071797            if ( $this->reconnect_retries === $tries && WP_DEBUG ) {
    18081798                error_reporting( $error_reporting );
     
    18541844        $this->bail( $message, 'db_connect_fail' );
    18551845
    1856         // Call dead_db() if bail didn't die, because this database is no more.
    1857         // It has ceased to be (at least temporarily).
     1846        // Call dead_db() if bail didn't die, because this database is no more. It has ceased to be (at least temporarily).
    18581847        dead_db();
    18591848    }
     
    19981987            }
    19991988
    2000             // Log number of rows the query returned
    2001             // and return number of rows selected.
     1989            // Log number of rows the query returned and return number of rows selected.
    20021990            $this->num_rows = $num_rows;
    20031991            $return_val     = $num_rows;
     
    21392127     * Insert a row into a table.
    21402128     *
     2129     * Examples:
    21412130     *     wpdb::insert( 'table', array( 'column' => 'foo', 'field' => 'bar' ) )
    21422131     *     wpdb::insert( 'table', array( 'column' => 'foo', 'field' => 1337 ), array( '%s', '%d' ) )
     
    21472136     * @see wp_set_wpdb_vars()
    21482137     *
    2149      * @param string       $table  Table name
     2138     * @param string       $table  Table name.
    21502139     * @param array        $data   Data to insert (in column => value pairs).
    21512140     *                             Both $data columns and $data values should be "raw" (neither should be SQL escaped).
    2152      *                             Sending a null value will cause the column to be set to NULL - the corresponding format is ignored in this case.
     2141     *                             Sending a null value will cause the column to be set to NULL - the corresponding
     2142     *                             format is ignored in this case.
    21532143     * @param array|string $format Optional. An array of formats to be mapped to each of the value in $data.
    21542144     *                             If string, that format will be used for all of the values in $data.
    21552145     *                             A format is one of '%d', '%f', '%s' (integer, float, string).
    2156      *                             If omitted, all values in $data will be treated as strings unless otherwise specified in wpdb::$field_types.
     2146     *                             If omitted, all values in $data will be treated as strings unless otherwise
     2147     *                             specified in wpdb::$field_types.
    21572148     * @return int|false The number of rows inserted, or false on error.
    21582149     */
     
    21642155     * Replace a row into a table.
    21652156     *
     2157     * Examples:
    21662158     *     wpdb::replace( 'table', array( 'column' => 'foo', 'field' => 'bar' ) )
    21672159     *     wpdb::replace( 'table', array( 'column' => 'foo', 'field' => 1337 ), array( '%s', '%d' ) )
     
    21722164     * @see wp_set_wpdb_vars()
    21732165     *
    2174      * @param string       $table  Table name
     2166     * @param string       $table  Table name.
    21752167     * @param array        $data   Data to insert (in column => value pairs).
    21762168     *                             Both $data columns and $data values should be "raw" (neither should be SQL escaped).
    2177      *                             Sending a null value will cause the column to be set to NULL - the corresponding format is ignored in this case.
     2169     *                             Sending a null value will cause the column to be set to NULL - the corresponding
     2170     *                             format is ignored in this case.
    21782171     * @param array|string $format Optional. An array of formats to be mapped to each of the value in $data.
    21792172     *                             If string, that format will be used for all of the values in $data.
    21802173     *                             A format is one of '%d', '%f', '%s' (integer, float, string).
    2181      *                             If omitted, all values in $data will be treated as strings unless otherwise specified in wpdb::$field_types.
     2174     *                             If omitted, all values in $data will be treated as strings unless otherwise
     2175     *                             specified in wpdb::$field_types.
    21822176     * @return int|false The number of rows affected, or false on error.
    21832177     */
     
    21992193     * @param array        $data   Data to insert (in column => value pairs).
    22002194     *                             Both $data columns and $data values should be "raw" (neither should be SQL escaped).
    2201      *                             Sending a null value will cause the column to be set to NULL - the corresponding format is ignored in this case.
     2195     *                             Sending a null value will cause the column to be set to NULL - the corresponding
     2196     *                             format is ignored in this case.
    22022197     * @param array|string $format Optional. An array of formats to be mapped to each of the value in $data.
    22032198     *                             If string, that format will be used for all of the values in $data.
    22042199     *                             A format is one of '%d', '%f', '%s' (integer, float, string).
    2205      *                             If omitted, all values in $data will be treated as strings unless otherwise specified in wpdb::$field_types.
     2200     *                             If omitted, all values in $data will be treated as strings unless otherwise
     2201     *                             specified in wpdb::$field_types.
    22062202     * @param string $type         Optional. What type of operation is this? INSERT or REPLACE. Defaults to INSERT.
    22072203     * @return int|false The number of rows affected, or false on error.
     
    22412237
    22422238    /**
    2243      * Update a row in the table
    2244      *
     2239     * Update a row in the table.
     2240     *
     2241     * Examples:
    22452242     *     wpdb::update( 'table', array( 'column' => 'foo', 'field' => 'bar' ), array( 'ID' => 1 ) )
    22462243     *     wpdb::update( 'table', array( 'column' => 'foo', 'field' => 1337 ), array( 'ID' => 1 ), array( '%s', '%d' ), array( '%d' ) )
     
    22592256     *                                   Multiple clauses will be joined with ANDs.
    22602257     *                                   Both $where columns and $where values should be "raw".
    2261      *                                   Sending a null value will create an IS NULL comparison - the corresponding format will be ignored in this case.
     2258     *                                   Sending a null value will create an IS NULL comparison - the corresponding
     2259     *                                   format will be ignored in this case.
    22622260     * @param array|string $format       Optional. An array of formats to be mapped to each of the values in $data.
    22632261     *                                   If string, that format will be used for all of the values in $data.
    22642262     *                                   A format is one of '%d', '%f', '%s' (integer, float, string).
    2265      *                                   If omitted, all values in $data will be treated as strings unless otherwise specified in wpdb::$field_types.
     2263     *                                   If omitted, all values in $data will be treated as strings unless otherwise
     2264     *                                   specified in wpdb::$field_types.
    22662265     * @param array|string $where_format Optional. An array of formats to be mapped to each of the values in $where.
    22672266     *                                   If string, that format will be used for all of the items in $where.
     
    23302329     *                                   Multiple clauses will be joined with ANDs.
    23312330     *                                   Both $where columns and $where values should be "raw".
    2332      *                                   Sending a null value will create an IS NULL comparison - the corresponding format will be ignored in this case.
     2331     *                                   Sending a null value will create an IS NULL comparison - the corresponding
     2332     *                                   format will be ignored in this case.
    23332333     * @param array|string $where_format Optional. An array of formats to be mapped to each of the values in $where.
    23342334     *                                   If string, that format will be used for all of the items in $where.
    23352335     *                                   A format is one of '%d', '%f', '%s' (integer, float, string).
    2336      *                                   If omitted, all values in $where will be treated as strings unless otherwise specified in wpdb::$field_types.
     2336     *                                   If omitted, all values in $data will be treated as strings unless otherwise
     2337     *                                   specified in wpdb::$field_types.
    23372338     * @return int|false The number of rows updated, or false on error.
    23382339     */
     
    23702371     * Processes arrays of field/value pairs and field formats.
    23712372     *
    2372      * This is a helper method for wpdb's CRUD methods, which take field/value
    2373      * pairs for inserts, updates, and where clauses. This method first pairs
    2374      * each value with a format. Then it determines the charset of that field,
    2375      * using that to determine if any invalid text would be stripped. If text is
    2376      * stripped, then field processing is rejected and the query fails.
     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.
    23772377     *
    23782378     * @since 4.2.0
     
    23812381     * @param array  $data   Field/value pair.
    23822382     * @param mixed  $format Format for each field.
    2383      * @return array|false Returns an array of fields that contain paired values
    2384      *                    and formats. Returns false for invalid values.
     2383     *
     2384     * @return array|false Returns an array of fields that contain paired value and formats. Returns false for
     2385     *                     invalid values.
    23852386     */
    23862387    protected function process_fields( $table, $data, $format ) {
     
    24162417     * @param array $data   Array of fields to values.
    24172418     * @param mixed $format Formats to be mapped to the values in $data.
    2418      * @return array Array, keyed by field names with values being an array
    2419      *               of 'value' and 'format' keys.
     2419     * @return array Array, keyed by field names with values being an array of 'value' and 'format' keys.
    24202420     */
    24212421    protected function process_field_formats( $data, $format ) {
     
    24452445
    24462446    /**
    2447      * Adds field charsets to field/value/format arrays generated by
    2448      * the wpdb::process_field_formats() method.
     2447     * Adds field charsets to field/value/format arrays generated by the wpdb::process_field_formats() method.
    24492448     *
    24502449     * @since 4.2.0
     
    25092508     * Retrieve one variable from the database.
    25102509     *
    2511      * Executes a SQL query and returns the value from the SQL result.
    2512      * If the SQL result contains more than one column and/or more than one row, this function returns the value in the column and row specified.
    2513      * If $query is null, this function returns the value in the specified column and row from the previous SQL result.
     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.
    25142513     *
    25152514     * @since 0.71
     
    25482547     *
    25492548     * @param string|null $query  SQL query.
    2550      * @param string      $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to
    2551      *                            an stdClass object, an associative array, or a numeric array, respectively. Default OBJECT.
     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.
    25522552     * @param int         $y      Optional. Row to return. Indexed from 0.
    25532553     * @return array|object|null|void Database query result in format specified by $output or null on failure
     
    25872587     * Retrieve one column from the database.
    25882588     *
    2589      * Executes a SQL query and returns the column from the SQL result.
    2590      * If the SQL result contains more than one column, this function returns the column specified.
    2591      * If $query is null, this function returns the specified column from the previous SQL result.
     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.
    25922592     *
    25932593     * @since 0.71
     
    26252625     * @param string $query  SQL query.
    26262626     * @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 number.
    2628      *                       Each row is an associative array (column => value, ...), a numerically indexed array (0 => value, ...), or an object. ( ->column = value ), respectively.
    2629      *                       With OBJECT_K, return an associative array of row objects keyed by the value of each row's first column's value.
    2630      *                       Duplicate keys are discarded.
    2631      * @return array|object|null Database query results
     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.
     2632     * @return array|object|null Database query results.
     2633     *
    26322634     */
    26332635    public function get_results( $query = null, $output = OBJECT ) {
     
    27902792     * @param string $table  Table name.
    27912793     * @param string $column Column name.
    2792      * @return string|false|WP_Error Column character set as a string. False if the column has no
    2793      *                               character set. WP_Error object if there was an error.
     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.
    27942796     */
    27952797    public function get_col_charset( $table, $column ) {
     
    28482850    /**
    28492851     * Retrieve the maximum string length allowed in a given column.
     2852     *
    28502853     * The length may either be specified as a byte length or a character length.
    28512854     *
     
    29392942     * Check if a string is ASCII.
    29402943     *
    2941      * The negative regex is faster for non-ASCII strings, as it allows
    2942      * the search to finish as soon as it encounters a non-ASCII character.
     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.
    29432946     *
    29442947     * @since 4.2.0
     
    30213024     * @since 4.2.0
    30223025     *
    3023      * @param array $data Array of value arrays. Each value array has the keys
    3024      *                    'value' and 'charset'. An optional 'ascii' key can be
    3025      *                    set to false to avoid redundant ASCII checks.
    3026      * @return array|WP_Error The $data parameter, with invalid characters removed from
    3027      *                        each value. This works as a passthrough: any additional keys
    3028      *                        such as 'field' are retained in each value array. If we cannot
    3029      *                        remove invalid characters, a WP_Error object is returned.
     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.
    30303031     */
    30313032    protected function strip_invalid_text( $data ) {
     
    30403041            } else {
    30413042                $length = false;
    3042                 /*
    3043                  * Since we have no length, we'll never truncate.
    3044                  * Initialize the variable to false. true would take us
    3045                  * through an unnecessary (for this case) codepath below.
    3046                  */
     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.
    30473045                $truncate_by_byte_length = false;
    30483046            }
     
    30603058            $needs_validation = true;
    30613059            if (
    3062                 // latin1 can store any byte sequence
     3060                // latin1 can store any byte sequence.
    30633061                'latin1' === $charset
    30643062            ||
     
    31833181     * @since 4.2.0
    31843182     *
    3185      * @param string $query Query to convert.
     3183     * @param string $query    Query to convert.
    31863184     * @return string|WP_Error The converted query, or a WP_Error object if the conversion fails.
    31873185     */
     
    33033301        /*
    33043302         * SHOW TABLE STATUS LIKE and SHOW TABLES LIKE 'wp\_123\_%'
    3305          * This quoted LIKE operand seldom holds a full table name.
    3306          * It is usually a pattern for matching a prefix so we just
    3307          * strip the trailing % and unescape the _ to get 'wp_123_'
    3308          * which drop-ins can use for routing these SQL statements.
     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.
    33093306         */
    33103307        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 ) ) {
     
    33663363     * @since 0.71
    33673364     *
    3368      * @param string $info_type  Optional. Type one of name, table, def, max_length, not_null, primary_key, multiple_key, unique_key, numeric, blob, type, unsigned, zerofill
    3369      * @param int    $col_offset Optional. 0: col name. 1: which table the col's in. 2: col's max length. 3: if the col is numeric. 4: col's type
     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
     3367     * @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
    33703369     * @return mixed Column Results
    33713370     */
     
    34183417     * @since 1.5.0
    34193418     *
    3420      * @param string $message    The error message.
    3421      * @param string $error_code Optional. A computer-readable string to identify the error.
    3422      * @return void|false Void if the showing of errors is enabled, false if disabled.
     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
    34233422     */
    34243423    public function bail( $message, $error_code = '500' ) {
     
    34623461     * @since 4.5.0
    34633462     *
    3464      * @return bool True if the connection was successfully closed, false if it wasn't,
    3465      *              or the connection doesn't exist.
     3463     * @return bool True if the connection was successfully closed, false if it wasn't, or if the connection doesn't exist.
    34663464     */
    34673465    public function close() {
     
    34903488     * @since 2.5.0
    34913489     *
    3492      * @global string $wp_version             The WordPress version string.
    3493      * @global string $required_mysql_version The required MySQL version string.
    3494      *
    3495      * @return void|WP_Error
     3490     * @global string $wp_version
     3491     * @global string $required_mysql_version
     3492     * @return WP_Error|void
    34963493     */
    34973494    public function check_database_version() {
     
    35503547     * @see wpdb::db_version()
    35513548     *
    3552      * @param string $db_cap The feature to check for. Accepts 'collation',
    3553      *                       'group_concat', 'subqueries', 'set_charset',
     3549     * @param string $db_cap The feature to check for. Accepts 'collation', 'group_concat', 'subqueries', 'set_charset',
    35543550     *                       'utf8mb4', or 'utf8mb4_520'.
    35553551     * @return int|false Whether the database feature is supported, false otherwise.
     
    35953591     * Retrieve the name of the function that called wpdb.
    35963592     *
    3597      * Searches up the list of functions until it reaches
    3598      * the one that would most logically had called this method.
     3593     * Searches up the list of functions until it reaches the one that would most logically had called this method.
    35993594     *
    36003595     * @since 2.5.0
Note: See TracChangeset for help on using the changeset viewer.