X-Git-Url: https://scripts.mit.edu/gitweb/autoinstalls/wordpress.git/blobdiff_plain/f5fcdc7994bb67cce809bc4777944ae8b7fad4a4..53f4633144ed68c8b8fb5861f992b5489894a940:/wp-includes/wp-db.php diff --git a/wp-includes/wp-db.php b/wp-includes/wp-db.php index 296a5d21..9ce6519b 100644 --- a/wp-includes/wp-db.php +++ b/wp-includes/wp-db.php @@ -84,19 +84,19 @@ class wpdb { * Amount of queries made * * @since 1.2.0 - * @access private + * @access public * @var int */ - var $num_queries = 0; + public $num_queries = 0; /** * Count of rows returned by previous query * * @since 0.71 - * @access private + * @access public * @var int */ - var $num_rows = 0; + public $num_rows = 0; /** * Count of affected rows by previous query @@ -114,7 +114,7 @@ class wpdb { * @access public * @var int */ - var $insert_id = 0; + public $insert_id = 0; /** * Last query made @@ -176,7 +176,7 @@ class wpdb { * @since 4.2.0 * @access private * @see wpdb::check_safe_collation() - * @var boolean + * @var bool */ private $checking_collation = false; @@ -216,10 +216,10 @@ class wpdb { * security precautions. * * @since 2.5.0 - * @access private + * @access public * @var string */ - var $prefix = ''; + public $prefix = ''; /** * WordPress base table prefix. @@ -607,10 +607,12 @@ class wpdb { * @link https://core.trac.wordpress.org/ticket/3354 * @since 2.0.8 * - * @param string $dbuser MySQL database user + * @global string $wp_version + * + * @param string $dbuser MySQL database user * @param string $dbpassword MySQL database password - * @param string $dbname MySQL database name - * @param string $dbhost MySQL database host + * @param string $dbname MySQL database name + * @param string $dbhost MySQL database host */ public function __construct( $dbuser, $dbpassword, $dbname, $dbhost ) { register_shutdown_function( array( $this, '__destruct' ) ); @@ -652,7 +654,7 @@ class wpdb { * * @see wpdb::__construct() * @since 2.0.8 - * @return bool true + * @return true */ public function __destruct() { return true; @@ -858,8 +860,8 @@ class wpdb { * * @since 2.5.0 * - * @param string $prefix Alphanumeric name for the new prefix. - * @param bool $set_table_names Optional. Whether the table names, e.g. wpdb::$posts, should be updated or not. + * @param string $prefix Alphanumeric name for the new prefix. + * @param bool $set_table_names Optional. Whether the table names, e.g. wpdb::$posts, should be updated or not. * @return string|WP_Error Old prefix or WP_Error on error */ public function set_prefix( $prefix, $set_table_names = true ) { @@ -897,6 +899,7 @@ class wpdb { * * @since 3.0.0 * @access public + * * @param int $blog_id * @param int $site_id Optional. * @return int previous blog id @@ -961,10 +964,10 @@ class wpdb { * @uses wpdb::$global_tables * @uses wpdb::$ms_global_tables * - * @param string $scope Optional. Can be all, global, ms_global, blog, or old tables. Defaults to all. - * @param bool $prefix Optional. Whether to include table prefixes. Default true. If blog - * prefix is requested, then the custom users and usermeta tables will be mapped. - * @param int $blog_id Optional. The blog_id to prefix. Defaults to wpdb::$blogid. Used only when prefix is requested. + * @param string $scope Optional. Can be all, global, ms_global, blog, or old tables. Defaults to all. + * @param bool $prefix Optional. Whether to include table prefixes. Default true. If blog + * prefix is requested, then the custom users and usermeta tables will be mapped. + * @param int $blog_id Optional. The blog_id to prefix. Defaults to wpdb::$blogid. Used only when prefix is requested. * @return array Table names. When a prefix is requested, the key is the unprefixed table name. */ public function tables( $scope = 'all', $prefix = true, $blog_id = 0 ) { @@ -1024,9 +1027,8 @@ class wpdb { * * @since 0.71 * - * @param string $db MySQL database name - * @param resource $dbh Optional link identifier. - * @return null Always null. + * @param string $db MySQL database name + * @param resource|null $dbh Optional link identifier. */ public function select( $db, $dbh = null ) { if ( is_null($dbh) ) @@ -1050,7 +1052,6 @@ class wpdb {

If you don\'t know how to set up a database you should contact your host. If all else fails you may find help at the WordPress Support Forums.

' ), htmlspecialchars( $db, ENT_QUOTES ), htmlspecialchars( $this->dbuser, ENT_QUOTES ) ), 'db_select_fail' ); } - return; } } @@ -1162,9 +1163,10 @@ class wpdb { * Escapes content by reference for insertion into the database, for security * * @uses wpdb::_real_escape() + * * @since 2.3.0 + * * @param string $string to escape - * @return void */ public function escape_by_ref( &$string ) { if ( ! is_float( $string ) ) @@ -1197,14 +1199,13 @@ class wpdb { * @link http://php.net/sprintf Description of syntax. * @since 2.3.0 * - * @param string $query Query statement with sprintf()-like placeholders - * @param array|mixed $args The array of variables to substitute into the query's placeholders if being called like - * {@link http://php.net/vsprintf vsprintf()}, or the first variable to substitute into the query's placeholders if - * being called like {@link http://php.net/sprintf sprintf()}. - * @param mixed $args,... further variables to substitute into the query's placeholders if being called like - * {@link http://php.net/sprintf sprintf()}. - * @return null|false|string Sanitized query string, null if there is no query, false if there is an error and string - * if there was something to prepare + * @param string $query Query statement with sprintf()-like placeholders + * @param array|mixed $args The array of variables to substitute into the query's placeholders if being called like + * {@link http://php.net/vsprintf vsprintf()}, or the first variable to substitute into the query's placeholders if + * being called like {@link http://php.net/sprintf sprintf()}. + * @param mixed $args,... further variables to substitute into the query's placeholders if being called like + * {@link http://php.net/sprintf sprintf()}. + * @return string|void Sanitized query string, if there is a query to prepare. */ public function prepare( $query, $args ) { if ( is_null( $query ) ) @@ -1261,7 +1262,7 @@ class wpdb { * @global array $EZSQL_ERROR Stores error information of query and error string * * @param string $str The error to display - * @return false|null False if the showing of errors is disabled. + * @return false|void False if the showing of errors is disabled. */ public function print_error( $str = '' ) { global $EZSQL_ERROR; @@ -1293,19 +1294,29 @@ class wpdb { // If there is an error then take note of it if ( is_multisite() ) { - $msg = "WordPress database error: [$str]\n{$this->last_query}\n"; - if ( defined( 'ERRORLOGFILE' ) ) + $msg = sprintf( + "%s [%s]\n%s\n", + __( 'WordPress database error:' ), + $str, + $this->last_query + ); + + if ( defined( 'ERRORLOGFILE' ) ) { error_log( $msg, 3, ERRORLOGFILE ); - if ( defined( 'DIEONDBERROR' ) ) + } + if ( defined( 'DIEONDBERROR' ) ) { wp_die( $msg ); + } } else { $str = htmlspecialchars( $str, ENT_QUOTES ); $query = htmlspecialchars( $this->last_query, ENT_QUOTES ); - print "
-

WordPress database error: [$str]
- $query

-
"; + printf( + '

%s [%s]
%s

', + __( 'WordPress database error:' ), + $str, + $query + ); } } @@ -1366,7 +1377,6 @@ class wpdb { * Kill cached query results. * * @since 0.71 - * @return void */ public function flush() { $this->last_result = array(); @@ -1403,10 +1413,9 @@ class wpdb { * @since 3.9.0 $allow_bail parameter added. * * @param bool $allow_bail Optional. Allows the function to bail. Default true. - * @return null|bool True with a successful connection, false on failure. + * @return bool True with a successful connection, false on failure. */ public function db_connect( $allow_bail = true ) { - $this->is_mysql = true; /* @@ -1528,7 +1537,7 @@ class wpdb { * @since 3.9.0 * * @param bool $allow_bail Optional. Allows the function to bail. Default true. - * @return bool|null True if the connection is up. + * @return bool|void True if the connection is up. */ public function check_connection( $allow_bail = true ) { if ( $this->use_mysqli ) { @@ -1758,10 +1767,13 @@ class wpdb { * @see wpdb::$field_types * @see wp_set_wpdb_vars() * - * @param string $table table name - * @param array $data Data to insert (in column => value pairs). Both $data columns and $data values should be "raw" (neither should be SQL escaped). - * @param array|string $format Optional. An array of formats to be mapped to each of the value in $data. If string, that format will be used for all of the values in $data. - * A format is one of '%d', '%f', '%s' (integer, float, string). If omitted, all values in $data will be treated as strings unless otherwise specified in wpdb::$field_types. + * @param string $table Table name + * @param array $data Data to insert (in column => value pairs). + * Both $data columns and $data values should be "raw" (neither should be SQL escaped). + * @param array|string $format Optional. An array of formats to be mapped to each of the value in $data. + * If string, that format will be used for all of the values in $data. + * A format is one of '%d', '%f', '%s' (integer, float, string). + * If omitted, all values in $data will be treated as strings unless otherwise specified in wpdb::$field_types. * @return int|false The number of rows inserted, or false on error. */ public function insert( $table, $data, $format = null ) { @@ -1779,10 +1791,13 @@ class wpdb { * @see wpdb::$field_types * @see wp_set_wpdb_vars() * - * @param string $table table name - * @param array $data Data to insert (in column => value pairs). Both $data columns and $data values should be "raw" (neither should be SQL escaped). - * @param array|string $format Optional. An array of formats to be mapped to each of the value in $data. If string, that format will be used for all of the values in $data. - * A format is one of '%d', '%f', '%s' (integer, float, string). If omitted, all values in $data will be treated as strings unless otherwise specified in wpdb::$field_types. + * @param string $table Table name + * @param array $data Data to insert (in column => value pairs). + * Both $data columns and $data values should be "raw" (neither should be SQL escaped). + * @param array|string $format Optional. An array of formats to be mapped to each of the value in $data. + * If string, that format will be used for all of the values in $data. + * A format is one of '%d', '%f', '%s' (integer, float, string). + * If omitted, all values in $data will be treated as strings unless otherwise specified in wpdb::$field_types. * @return int|false The number of rows affected, or false on error. */ public function replace( $table, $data, $format = null ) { @@ -1800,11 +1815,14 @@ class wpdb { * @see wpdb::$field_types * @see wp_set_wpdb_vars() * - * @param string $table table name - * @param array $data Data to insert (in column => value pairs). Both $data columns and $data values should be "raw" (neither should be SQL escaped). - * @param array|string $format Optional. An array of formats to be mapped to each of the value in $data. If string, that format will be used for all of the values in $data. - * A format is one of '%d', '%f', '%s' (integer, float, string). If omitted, all values in $data will be treated as strings unless otherwise specified in wpdb::$field_types. - * @param string $type Optional. What type of operation is this? INSERT or REPLACE. Defaults to INSERT. + * @param string $table Table name + * @param array $data Data to insert (in column => value pairs). + * Both $data columns and $data values should be "raw" (neither should be SQL escaped). + * @param array|string $format Optional. An array of formats to be mapped to each of the value in $data. + * If string, that format will be used for all of the values in $data. + * A format is one of '%d', '%f', '%s' (integer, float, string). + * If omitted, all values in $data will be treated as strings unless otherwise specified in wpdb::$field_types. + * @param string $type Optional. What type of operation is this? INSERT or REPLACE. Defaults to INSERT. * @return int|false The number of rows affected, or false on error. */ function _insert_replace_helper( $table, $data, $format = null, $type = 'INSERT' ) { @@ -1845,12 +1863,20 @@ class wpdb { * @see wpdb::$field_types * @see wp_set_wpdb_vars() * - * @param string $table table name - * @param array $data Data to update (in column => value pairs). Both $data columns and $data values should be "raw" (neither should be SQL escaped). - * @param array $where A named array of WHERE clauses (in column => value pairs). Multiple clauses will be joined with ANDs. Both $where columns and $where values should be "raw". - * @param array|string $format Optional. An array of formats to be mapped to each of the values in $data. If string, that format will be used for all of the values in $data. - * A format is one of '%d', '%f', '%s' (integer, float, string). If omitted, all values in $data will be treated as strings unless otherwise specified in wpdb::$field_types. - * @param array|string $where_format Optional. An array of formats to be mapped to each of the values in $where. If string, that format will be used for all of the items in $where. A format is one of '%d', '%f', '%s' (integer, float, string). If omitted, all values in $where will be treated as strings. + * @param string $table Table name + * @param array $data Data to update (in column => value pairs). + * Both $data columns and $data values should be "raw" (neither should be SQL escaped). + * @param array $where A named array of WHERE clauses (in column => value pairs). + * Multiple clauses will be joined with ANDs. + * Both $where columns and $where values should be "raw". + * @param array|string $format Optional. An array of formats to be mapped to each of the values in $data. + * If string, that format will be used for all of the values in $data. + * A format is one of '%d', '%f', '%s' (integer, float, string). + * If omitted, all values in $data will be treated as strings unless otherwise specified in wpdb::$field_types. + * @param array|string $where_format Optional. An array of formats to be mapped to each of the values in $where. + * If string, that format will be used for all of the items in $where. + * A format is one of '%d', '%f', '%s' (integer, float, string). + * If omitted, all values in $where will be treated as strings. * @return int|false The number of rows updated, or false on error. */ public function update( $table, $data, $where, $format = null, $where_format = null ) { @@ -1897,9 +1923,14 @@ class wpdb { * @see wpdb::$field_types * @see wp_set_wpdb_vars() * - * @param string $table table name - * @param array $where A named array of WHERE clauses (in column => value pairs). Multiple clauses will be joined with ANDs. Both $where columns and $where values should be "raw". - * @param array|string $where_format Optional. An array of formats to be mapped to each of the values in $where. If string, that format will be used for all of the items in $where. A format is one of '%d', '%f', '%s' (integer, float, string). If omitted, all values in $where will be treated as strings unless otherwise specified in wpdb::$field_types. + * @param string $table Table name + * @param array $where A named array of WHERE clauses (in column => value pairs). + * Multiple clauses will be joined with ANDs. + * Both $where columns and $where values should be "raw". + * @param array|string $where_format Optional. An array of formats to be mapped to each of the values in $where. + * If string, that format will be used for all of the items in $where. + * A format is one of '%d', '%f', '%s' (integer, float, string). + * If omitted, all values in $where will be treated as strings unless otherwise specified in wpdb::$field_types. * @return int|false The number of rows updated, or false on error. */ public function delete( $table, $where, $where_format = null ) { @@ -1941,7 +1972,7 @@ class wpdb { * @param string $table Table name. * @param array $data Field/value pair. * @param mixed $format Format for each field. - * @return array|bool Returns an array of fields that contain paired values + * @return array|false Returns an array of fields that contain paired values * and formats. Returns false for invalid values. */ protected function process_fields( $table, $data, $format ) { @@ -2013,7 +2044,7 @@ class wpdb { * * @param array $data As it comes from the wpdb::process_field_formats() method. * @param string $table Table name. - * @return The same array as $data with additional 'charset' keys. + * @return array|false The same array as $data with additional 'charset' keys. */ protected function process_field_charsets( $data, $table ) { foreach ( $data as $field => $value ) { @@ -2042,7 +2073,7 @@ class wpdb { * * @param array $data As it comes from the wpdb::process_field_charsets() method. * @param string $table Table name. - * @return array|False The same array as $data with additional 'length' keys, or false if + * @return array|false The same array as $data with additional 'length' keys, or false if * any of the values were too long for their corresponding field. */ protected function process_field_lengths( $data, $table ) { @@ -2074,8 +2105,8 @@ class wpdb { * @since 0.71 * * @param string|null $query Optional. SQL query. Defaults to null, use the result from the previous query. - * @param int $x Optional. Column of value to return. Indexed from 0. - * @param int $y Optional. Row of value to return. Indexed from 0. + * @param int $x Optional. Column of value to return. Indexed from 0. + * @param int $y Optional. Row of value to return. Indexed from 0. * @return string|null Database query result (as string), or null on failure */ public function get_var( $query = null, $x = 0, $y = 0 ) { @@ -2105,11 +2136,13 @@ class wpdb { * * @since 0.71 * - * @param string|null $query SQL query. - * @param string $output Optional. one of ARRAY_A | ARRAY_N | OBJECT constants. Return an associative array (column => value, ...), - * a numerically indexed array (0 => value, ...) or an object ( ->column = value ), respectively. - * @param int $y Optional. Row to return. Indexed from 0. - * @return mixed Database query result in format specified by $output or null on failure + * @param string|null $query SQL query. + * @param string $output Optional. one of ARRAY_A | ARRAY_N | OBJECT constants. + * Return an associative array (column => value, ...), + * a numerically indexed array (0 => value, ...) or + * an object ( ->column = value ), respectively. + * @param int $y Optional. Row to return. Indexed from 0. + * @return array|object|null|void Database query result in format specified by $output or null on failure */ public function get_row( $query = null, $output = OBJECT, $y = 0 ) { $this->func_call = "\$db->get_row(\"$query\",$output,$y)"; @@ -2151,7 +2184,7 @@ class wpdb { * @since 0.71 * * @param string|null $query Optional. SQL query. Defaults to previous query. - * @param int $x Optional. Column to return. Indexed from 0. + * @param int $x Optional. Column to return. Indexed from 0. * @return array Database query result. Array indexed from 0 by SQL result row number. */ public function get_col( $query = null , $x = 0 ) { @@ -2178,11 +2211,13 @@ class wpdb { * * @since 0.71 * - * @param string $query SQL query. - * @param string $output Optional. Any of ARRAY_A | ARRAY_N | OBJECT | OBJECT_K constants. With one of the first three, return an array of rows indexed from 0 by SQL result row number. - * Each row is an associative array (column => value, ...), a numerically indexed array (0 => value, ...), or an object. ( ->column = value ), respectively. - * With OBJECT_K, return an associative array of row objects keyed by the value of each row's first column's value. Duplicate keys are discarded. - * @return mixed Database query results + * @param string $query SQL query. + * @param string $output Optional. Any of ARRAY_A | ARRAY_N | OBJECT | OBJECT_K constants. + * With one of the first three, return an array of rows indexed from 0 by SQL result row number. + * Each row is an associative array (column => value, ...), a numerically indexed array (0 => value, ...), or an object. ( ->column = value ), respectively. + * With OBJECT_K, return an associative array of row objects keyed by the value of each row's first column's value. + * Duplicate keys are discarded. + * @return array|object|null Database query results */ public function get_results( $query = null, $output = OBJECT ) { $this->func_call = "\$db->get_results(\"$query\", $output)"; @@ -2341,8 +2376,8 @@ class wpdb { * * @param string $table Table name. * @param string $column Column name. - * @return mixed Column character set as a string. False if the column has no - * character set. WP_Error object if there was an error. + * @return string|false|WP_Error Column character set as a string. False if the column has no + * character set. WP_Error object if there was an error. */ public function get_col_charset( $table, $column ) { $tablekey = strtolower( $table ); @@ -2406,9 +2441,9 @@ class wpdb { * * @param string $table Table name. * @param string $column Column name. - * @return mixed array( 'length' => (int), 'type' => 'byte' | 'char' ) - * false if the column has no length (for example, numeric column) - * WP_Error object if there was an error. + * @return array|false|WP_Error array( 'length' => (int), 'type' => 'byte' | 'char' ) + * false if the column has no length (for example, numeric column) + * WP_Error object if there was an error. */ public function get_col_length( $table, $column ) { $tablekey = strtolower( $table ); @@ -2835,7 +2870,7 @@ class wpdb { . '|REPLACE(?:\s+LOW_PRIORITY|\s+DELAYED)?(?:\s+INTO)?' . '|UPDATE(?:\s+LOW_PRIORITY)?(?:\s+IGNORE)?' . '|DELETE(?:\s+LOW_PRIORITY|\s+QUICK|\s+IGNORE)*(?:\s+FROM)?' - . ')\s+((?:[0-9a-zA-Z$_.`-]|[\xC2-\xDF][\x80-\xBF])+)/is', $query, $maybe ) ) { + . ')\s+((?:[0-9a-zA-Z$_.`]|[\xC2-\xDF][\x80-\xBF])+)/is', $query, $maybe ) ) { return str_replace( '`', '', $maybe[1] ); } @@ -2843,7 +2878,7 @@ class wpdb { if ( preg_match( '/^\s*(?:' . 'SHOW\s+TABLE\s+STATUS.+(?:LIKE\s+|WHERE\s+Name\s*=\s*)' . '|SHOW\s+(?:FULL\s+)?TABLES.+(?:LIKE\s+|WHERE\s+Name\s*=\s*)' - . ')\W((?:[0-9a-zA-Z$_.`-]|[\xC2-\xDF][\x80-\xBF])+)\W/is', $query, $maybe ) ) { + . ')\W((?:[0-9a-zA-Z$_.`]|[\xC2-\xDF][\x80-\xBF])+)\W/is', $query, $maybe ) ) { return str_replace( '`', '', $maybe[1] ); } @@ -2862,7 +2897,7 @@ class wpdb { . '|LOAD\s+DATA.*INFILE.*INTO\s+TABLE' . '|(?:GRANT|REVOKE).*ON\s+TABLE' . '|SHOW\s+(?:.*FROM|.*TABLE)' - . ')\s+\(*\s*((?:[0-9a-zA-Z$_.`-]|[\xC2-\xDF][\x80-\xBF])+)\s*\)*/is', $query, $maybe ) ) { + . ')\s+\(*\s*((?:[0-9a-zA-Z$_.`]|[\xC2-\xDF][\x80-\xBF])+)\s*\)*/is', $query, $maybe ) ) { return str_replace( '`', '', $maybe[1] ); } @@ -2881,11 +2916,13 @@ class wpdb { return; if ( $this->use_mysqli ) { - for ( $i = 0; $i < @mysqli_num_fields( $this->result ); $i++ ) { + $num_fields = @mysqli_num_fields( $this->result ); + for ( $i = 0; $i < $num_fields; $i++ ) { $this->col_info[ $i ] = @mysqli_fetch_field( $this->result ); } } else { - for ( $i = 0; $i < @mysql_num_fields( $this->result ); $i++ ) { + $num_fields = @mysql_num_fields( $this->result ); + for ( $i = 0; $i < $num_fields; $i++ ) { $this->col_info[ $i ] = @mysql_fetch_field( $this->result, $i ); } } @@ -2896,8 +2933,8 @@ class wpdb { * * @since 0.71 * - * @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 - * @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 + * @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 + * @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 * @return mixed Column Results */ public function get_col_info( $info_type = 'name', $col_offset = -1 ) { @@ -2923,7 +2960,7 @@ class wpdb { * * @since 1.5.0 * - * @return bool + * @return true */ public function timer_start() { $this->time_start = microtime( true ); @@ -2948,7 +2985,7 @@ class wpdb { * * @since 1.5.0 * - * @param string $message The Error message + * @param string $message The Error message * @param string $error_code Optional. A Computer readable string to identify the error. * @return false|void */ @@ -2967,10 +3004,11 @@ class wpdb { * Whether MySQL database is at least the required minimum version. * * @since 2.5.0 - * @uses $wp_version - * @uses $required_mysql_version * - * @return WP_Error + * @global string $wp_version + * @global string $required_mysql_version + * + * @return WP_Error|void */ public function check_database_version() { global $wp_version, $required_mysql_version; @@ -3024,7 +3062,7 @@ class wpdb { * @param string $db_cap The feature to check for. Accepts 'collation', * 'group_concat', 'subqueries', 'set_charset', * or 'utf8mb4'. - * @return bool Whether the database feature is supported, false otherwise. + * @return int|false Whether the database feature is supported, false otherwise. */ public function has_cap( $db_cap ) { $version = $this->db_version(); @@ -3069,7 +3107,7 @@ class wpdb { * * @since 2.5.0 * - * @return string The name of the calling function + * @return string|array The name of the calling function */ public function get_caller() { return wp_debug_backtrace_summary( __CLASS__ );