![(please configure the [header_logo] section in trac.ini)](/chrome/site/your_project_logo.png){kind=logo}
Changeset 47749
- Timestamp:
- 05/03/2020 11:43:14 AM (6 years ago)
- File:
-
- 1 edited
-
trunk/src/wp-includes/wp-db.php (modified) (84 diffs)
Legend:
- Unmodified
- Added
- Removed
-
trunk/src/wp-includes/wp-db.php
r47740 r47749 38 38 39 39 /** 40 * WordPress database access abstraction class 40 * WordPress database access abstraction class. 41 41 * 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. 44 49 * 45 50 * @link https://developer.wordpress.org/reference/classes/wpdb/ … … 68 73 69 74 /** 70 * The lasterror encountered during the last query.75 * The error encountered during the last query. 71 76 * 72 77 * @since 2.5.0 … … 188 193 * @type string $0 The query's SQL. 189 194 * @type float $1 Total time spent on the query, in seconds. 190 * @type string $2 Comma 195 * @type string $2 Comma-separated list of the calling functions. 191 196 * @type float $3 Unix timestamp of the time at the start of the query. 192 197 * @type array $4 Custom query data. … … 271 276 * List of deprecated WordPress tables. 272 277 * 273 * categories, post2cat, and link2catwere deprecated in 2.3.0, db version 5539.278 * 'categories', 'post2cat', and 'link2cat' were deprecated in 2.3.0, db version 5539. 274 279 * 275 280 * @since 2.9.0 … … 462 467 463 468 /** 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'. 467 473 * 468 474 * @since 2.8.0 … … 543 549 * Whether MySQL is used as the database engine. 544 550 * 545 * Set in WPDB::db_connect() to true, by default. This is used when checking551 * Set in wpdb::db_connect() to true, by default. This is used when checking 546 552 * against the required MySQL version for WordPress. Normally, a replacement 547 553 * database drop-in (db.php) will skip these checks, but setting this to true … … 587 593 * Connects to the database server and selects a database. 588 594 * 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 591 599 * 592 600 * @link https://core.trac.wordpress.org/ticket/3354 593 * @since 2.0.8594 *595 601 * @global string $wp_version The WordPress version string. 596 602 * … … 633 639 * 634 640 * @param string $name The private member to get, and optionally process. 635 * @return mixed 641 * @return mixed The private member. 636 642 */ 637 643 public function __get( $name ) { … … 668 674 * @since 3.5.0 669 675 * 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. 673 678 */ 674 679 public function __isset( $name ) { … … 688 693 689 694 /** 690 * Set $this->charset and $this->collate695 * Sets $this->charset and $this->collate. 691 696 * 692 697 * @since 3.1.0 … … 811 816 812 817 /** 813 * Change the current SQL mode, and ensureits WordPress compatibility.818 * Changes the current SQL mode, and ensures its WordPress compatibility. 814 819 * 815 820 * If no modes are passed, it will ensure the current MySQL server modes are compatible. … … 817 822 * @since 3.9.0 818 823 * 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. 820 825 */ 821 826 public function set_sql_mode( $modes = array() ) { … … 880 885 * 881 886 * @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. 883 889 * @return string|WP_Error Old prefix or WP_Error on error. 884 890 */ … … 953 959 * 954 960 * @since 3.0.0 961 * 955 962 * @param int $blog_id Optional. 956 963 * @return string Blog prefix. … … 975 982 * Returns an array of WordPress tables. 976 983 * 977 * Also allows for the CUSTOM_USER_TABLE and CUSTOM_USER_META_TABLE to override the WordPress users and usermeta978 * 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. 979 986 * 980 987 * The $scope argument can take one of the following: … … 982 989 * 'all' - returns 'all' and 'global' tables. No old tables are returned. 983 990 * 'blog' - returns the blog-level tables for the queried blog. 984 * 'global' - returns the global tables for the installation, returning multisite tables only if runningmultisite.991 * 'global' - returns the global tables for the installation, returning multisite tables only on multisite. 985 992 * 'ms_global' - returns the multisite global tables, regardless if current installation is multisite. 986 993 * 'old' - returns tables which are deprecated. 987 994 * 988 995 * @since 3.0.0 996 * 989 997 * @uses wpdb::$tables 990 998 * @uses wpdb::$old_tables … … 992 1000 * @uses wpdb::$ms_global_tables 993 1001 * 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. 998 1008 * @return array Table names. When a prefix is requested, the key is the unprefixed table name. 999 1009 */ … … 1056 1066 * Selects a database using the current database connection. 1057 1067 * 1058 * The database name will be changed based on the current database connection. On failure, the execution will1059 * 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. 1060 1070 * 1061 1071 * @since 0.71 1062 1072 * 1063 * @param string $db MySQL database name 1073 * @param string $db MySQL database name. 1064 1074 * @param resource|null $dbh Optional link identifier. 1065 1075 */ … … 1123 1133 * @since 2.8.0 1124 1134 * @deprecated 3.6.0 Use wpdb::prepare() 1125 * @see wpdb::prepare 1135 * @see wpdb::prepare() 1126 1136 * @see esc_sql() 1127 1137 * … … 1137 1147 1138 1148 /** 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 1140 1152 * 1141 1153 * @see mysqli_real_escape_string() 1142 1154 * @see mysql_real_escape_string() 1143 * @since 2.8.01144 1155 * 1145 1156 * @param string $string String to escape. … … 1168 1179 1169 1180 /** 1170 * Escape data. Works on arrays. 1181 * Escapes data. Works on arrays. 1182 * 1183 * @since 2.8.0 1171 1184 * 1172 1185 * @uses wpdb::_real_escape() 1173 * @since 2.8.01174 1186 * 1175 1187 * @param string|array $data Data to escape. … … 1202 1214 * @see esc_sql() 1203 1215 * 1204 * @param mixed $data1205 * @return mixed1216 * @param string|array $data Data to escape. 1217 * @return string|array Escaped data, in the same type as supplied. 1206 1218 */ 1207 1219 public function escape( $data ) { … … 1247 1259 * %s (string) 1248 1260 * 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. 1262 1275 * 1263 1276 * Examples: … … 1265 1278 * $wpdb->prepare( "SELECT DATE_FORMAT(`field`, '%%c') FROM `table` WHERE `column` = %s", 'foo' ); 1266 1279 * 1267 * @link https://www.php.net/sprintf Description of syntax.1268 1280 * @since 2.3.0 1269 1281 * @since 5.3.0 Formalized the existing and already documented `...$args` parameter … … 1271 1283 * from `$args` to `...$args`. 1272 1284 * 1285 * @link https://www.php.net/sprintf Description of syntax. 1286 * 1273 1287 * @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 1278 1291 * individual arguments. 1279 * 1292 * @param mixed ...$args Further variables to substitute into the query's placeholders 1293 * if being called with individual arguments. 1280 1294 * @return string|void Sanitized query string, if there is a query to prepare. 1281 1295 */ … … 1389 1403 * First half of escaping for LIKE special characters % and _ before preparing for MySQL. 1390 1404 * 1391 * Use this only before wpdb::prepare() or esc_sql(). 1405 * Use this only before wpdb::prepare() or esc_sql(). Reversing the order is very bad for security. 1392 1406 * 1393 1407 * Example Prepared Statement: … … 1404 1418 * @since 4.0.0 1405 1419 * 1406 * @param string $text The raw text to be escaped. The input typed by the user should have no1407 * 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_escapenext.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. 1410 1424 */ 1411 1425 public function esc_like( $text ) { … … 1414 1428 1415 1429 /** 1416 * Print SQL/DB error.1430 * Prints SQL/DB error. 1417 1431 * 1418 1432 * @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. 1422 1437 * @return void|false Void if the showing of errors is enabled, false if disabled. 1423 1438 */ … … 1490 1505 * Enables showing of database errors. 1491 1506 * 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 1494 1511 * 1495 1512 * @see wpdb::hide_errors() 1496 1513 * 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. 1501 1515 * @return bool Whether showing of errors was previously active. 1502 1516 */ … … 1513 1527 * 1514 1528 * @since 0.71 1529 * 1515 1530 * @see wpdb::show_errors() 1516 1531 * … … 1524 1539 1525 1540 /** 1526 * Whether to suppressdatabase 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. 1529 1544 * 1530 1545 * @since 2.5.0 1546 * 1531 1547 * @see wpdb::hide_errors() 1532 1548 * 1533 * @param bool $suppress Optional. New value. Defaults totrue.1534 * @return bool Old value1549 * @param bool $suppress Optional. Whether to suppress errors. Default true. 1550 * @return bool Whether suppressing of errors was previously active. 1535 1551 */ 1536 1552 public function suppress_errors( $suppress = true ) { … … 1541 1557 1542 1558 /** 1543 * Kill cached query results.1559 * Kills cached query results. 1544 1560 * 1545 1561 * @since 0.71 … … 1572 1588 1573 1589 /** 1574 * Connect to and selectdatabase.1590 * Connects to and selects database. 1575 1591 * 1576 1592 * If $allow_bail is false, the lack of database connection will need to be handled manually. … … 1606 1622 1607 1623 /* 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. 1611 1626 * @see https://bugs.php.net/bug.php?id=67563 1612 1627 */ … … 1708 1723 1709 1724 /** 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. 1714 1730 * 1715 1731 * @since 4.9.0 1716 1732 * 1717 1733 * @param string $host The DB_HOST setting to parse. 1718 * @return array| bool Array containing the host, the port, the socket and whether1719 * 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. 1721 1737 */ 1722 1738 public function parse_db_host( $host ) { … … 1763 1779 * Checks that the connection to the database is still up. If not, try to reconnect. 1764 1780 * 1765 * If this function is unable to reconnect, it will forcibly die, or if after the {@see 'template_redirect'} hook1766 * 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. 1767 1783 * 1768 1784 * If $allow_bail is false, the lack of database connection will need to be handled manually. … … 1793 1809 1794 1810 for ( $tries = 1; $tries <= $this->reconnect_retries; $tries++ ) { 1795 // On the last try, re-enable warnings. We want to see a single instance of the1796 // "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. 1797 1813 if ( $this->reconnect_retries === $tries && WP_DEBUG ) { 1798 1814 error_reporting( $error_reporting ); … … 1844 1860 $this->bail( $message, 'db_connect_fail' ); 1845 1861 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). 1847 1864 dead_db(); 1848 1865 } 1849 1866 1850 1867 /** 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. 1854 1871 * 1855 1872 * @since 0.71 1856 1873 * 1857 * @param string $query Database query 1874 * @link https://codex.wordpress.org/Function_Reference/wpdb_Class 1875 * 1876 * @param string $query Database query. 1858 1877 * @return int|bool Boolean true for CREATE, ALTER, TRUNCATE and DROP queries. Number of rows 1859 1878 * affected/selected for all other queries. Boolean false on error. … … 1987 2006 } 1988 2007 1989 // Log number of rows the query returned and returnnumber of rows selected.2008 // Log and return the number of rows selected. 1990 2009 $this->num_rows = $num_rows; 1991 2010 $return_val = $num_rows; … … 2034 2053 * @param string $query The query's SQL. 2035 2054 * @param float $query_time Total time spent on the query, in seconds. 2036 * @param string $query_callstack Comma 2055 * @param string $query_callstack Comma-separated list of the calling functions. 2037 2056 * @param float $query_start Unix timestamp of the time at the start of the query. 2038 2057 * @param array $query_data Custom query data. 2039 * }2040 2058 */ 2041 2059 public function log_query( $query, $query_time, $query_callstack, $query_start, $query_data ) { … … 2052 2070 * @param string $query The query's SQL. 2053 2071 * @param float $query_time Total time spent on the query, in seconds. 2054 * @param string $query_callstack Comma 2072 * @param string $query_callstack Comma-separated list of the calling functions. 2055 2073 * @param float $query_start Unix timestamp of the time at the start of the query. 2056 2074 */ … … 2125 2143 2126 2144 /** 2127 * Insert a row into atable.2145 * Inserts a row into the table. 2128 2146 * 2129 2147 * Examples: … … 2132 2150 * 2133 2151 * @since 2.5.0 2152 * 2134 2153 * @see wpdb::prepare() 2135 2154 * @see wpdb::$field_types … … 2153 2172 2154 2173 /** 2155 * Replace a row into atable.2174 * Replaces a row in the table. 2156 2175 * 2157 2176 * Examples: … … 2160 2179 * 2161 2180 * @since 3.0.0 2181 * 2162 2182 * @see wpdb::prepare() 2163 2183 * @see wpdb::$field_types … … 2186 2206 * 2187 2207 * @since 3.0.0 2208 * 2188 2209 * @see wpdb::prepare() 2189 2210 * @see wpdb::$field_types 2190 2211 * @see wp_set_wpdb_vars() 2191 2212 * 2192 * @param string $table Table name 2213 * @param string $table Table name. 2193 2214 * @param array $data Data to insert (in column => value pairs). 2194 2215 * Both $data columns and $data values should be "raw" (neither should be SQL escaped). … … 2200 2221 * If omitted, all values in $data will be treated as strings unless otherwise 2201 2222 * 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'. 2203 2225 * @return int|false The number of rows affected, or false on error. 2204 2226 */ … … 2237 2259 2238 2260 /** 2239 * Update a row in the table.2261 * Updates a row in the table. 2240 2262 * 2241 2263 * Examples: … … 2244 2266 * 2245 2267 * @since 2.5.0 2268 * 2246 2269 * @see wpdb::prepare() 2247 2270 * @see wpdb::$field_types 2248 2271 * @see wp_set_wpdb_vars() 2249 2272 * 2250 * @param string $table Table name 2273 * @param string $table Table name. 2251 2274 * @param array $data Data to update (in column => value pairs). 2252 2275 * Both $data columns and $data values should be "raw" (neither should be SQL escaped). … … 2315 2338 2316 2339 /** 2317 * Delete a row in the table 2318 * 2340 * Deletes a row in the table. 2341 * 2342 * Examples: 2319 2343 * wpdb::delete( 'table', array( 'ID' => 1 ) ) 2320 2344 * wpdb::delete( 'table', array( 'ID' => 1 ), array( '%d' ) ) 2321 2345 * 2322 2346 * @since 3.4.0 2347 * 2323 2348 * @see wpdb::prepare() 2324 2349 * @see wpdb::$field_types 2325 2350 * @see wp_set_wpdb_vars() 2326 2351 * 2327 * @param string $table Table name 2352 * @param string $table Table name. 2328 2353 * @param array $where A named array of WHERE clauses (in column => value pairs). 2329 2354 * Multiple clauses will be joined with ANDs. … … 2371 2396 * Processes arrays of field/value pairs and field formats. 2372 2397 * 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. 2377 2403 * 2378 2404 * @since 4.2.0 … … 2381 2407 * @param array $data Field/value pair. 2382 2408 * @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. 2386 2411 */ 2387 2412 protected function process_fields( $table, $data, $format ) { … … 2417 2442 * @param array $data Array of fields to values. 2418 2443 * @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. 2420 2446 */ 2421 2447 protected function process_field_formats( $data, $format ) { … … 2445 2471 2446 2472 /** 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(). 2448 2474 * 2449 2475 * @since 4.2.0 … … 2452 2478 * @param string $table Table name. 2453 2479 * @return array|false The same array as $data with additional 'charset' keys. 2480 * False on failure. 2454 2481 */ 2455 2482 protected function process_field_charsets( $data, $table ) { … … 2475 2502 2476 2503 /** 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. 2478 2505 * 2479 2506 * @since 4.2.1 … … 2506 2533 2507 2534 /** 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. 2513 2541 * 2514 2542 * @since 0.71 … … 2517 2545 * @param int $x Optional. Column of value to return. Indexed from 0. 2518 2546 * @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. 2520 2548 */ 2521 2549 public function get_var( $query = null, $x = 0, $y = 0 ) { … … 2530 2558 } 2531 2559 2532 // Extract var out of cached results based x,y vals.2560 // Extract var out of cached results based on x,y vals. 2533 2561 if ( ! empty( $this->last_result[ $y ] ) ) { 2534 2562 $values = array_values( get_object_vars( $this->last_result[ $y ] ) ); 2535 2563 } 2536 2564 2537 // If there is a value return it else return null.2565 // If there is a value return it, else return null. 2538 2566 return ( isset( $values[ $x ] ) && '' !== $values[ $x ] ) ? $values[ $x ] : null; 2539 2567 } 2540 2568 2541 2569 /** 2542 * Retrieve one row from the database.2570 * Retrieves one row from the database. 2543 2571 * 2544 2572 * Executes a SQL query and returns the row from the SQL result. … … 2547 2575 * 2548 2576 * @param string|null $query SQL query. 2549 * @param string $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which2550 * 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. 2552 2580 * @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. 2554 2582 */ 2555 2583 public function get_row( $query = null, $output = OBJECT, $y = 0 ) { … … 2585 2613 2586 2614 /** 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 from2591 * 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. 2592 2620 * 2593 2621 * @since 0.71 … … 2617 2645 2618 2646 /** 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). 2620 2648 * 2621 2649 * Executes a SQL query and returns the entire SQL result. … … 2625 2653 * @param string $query SQL query. 2626 2654 * @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. 2632 2661 * @return array|object|null Database query results. 2633 2662 * … … 2792 2821 * @param string $table Table name. 2793 2822 * @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. 2796 2825 */ 2797 2826 public function get_col_charset( $table, $column ) { … … 2849 2878 2850 2879 /** 2851 * Retrieve the maximum string length allowed in a given column.2880 * Retrieves the maximum string length allowed in a given column. 2852 2881 * 2853 2882 * The length may either be specified as a byte length or a character length. … … 2857 2886 * @param string $table Table name. 2858 2887 * @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). 2861 2890 * WP_Error object if there was an error. 2862 2891 */ … … 2940 2969 2941 2970 /** 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 encounters2945 * 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. 2946 2975 * 2947 2976 * @since 4.2.0 … … 2963 2992 2964 2993 /** 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. 2966 2995 * 2967 2996 * @since 4.2.0 … … 3024 3053 * @since 4.2.0 3025 3054 * 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. 3031 3061 */ 3032 3062 protected function strip_invalid_text( $data ) { … … 3041 3071 } else { 3042 3072 $length = false; 3043 // Since we have no length, we'll never truncate. Initialize the variable to false. true would take us3044 // 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. 3045 3075 $truncate_by_byte_length = false; 3046 3076 } … … 3181 3211 * @since 4.2.0 3182 3212 * 3183 * @param string $query 3213 * @param string $query Query to convert. 3184 3214 * @return string|WP_Error The converted query, or a WP_Error object if the conversion fails. 3185 3215 */ … … 3262 3292 3263 3293 /** 3264 * Find the first table name referenced in a query.3294 * Finds the first table name referenced in a query. 3265 3295 * 3266 3296 * @since 4.2.0 … … 3301 3331 /* 3302 3332 * 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. 3306 3337 */ 3307 3338 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 ) ) { … … 3336 3367 3337 3368 /** 3338 * Load the column metadata from the last query.3369 * Loads the column metadata from the last query. 3339 3370 * 3340 3371 * @since 3.5.0 … … 3359 3390 3360 3391 /** 3361 * Retrieve column metadata from the last query.3392 * Retrieves column metadata from the last query. 3362 3393 * 3363 3394 * @since 0.71 3364 3395 * 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'. 3367 3399 * @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 Results3400 * 3: if the col is numeric. 4: col's type. Default -1. 3401 * @return mixed Column results. 3370 3402 */ 3371 3403 public function get_col_info( $info_type = 'name', $col_offset = -1 ) { … … 3417 3449 * @since 1.5.0 3418 3450 * 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. 3422 3455 */ 3423 3456 public function bail( $message, $error_code = '500' ) { … … 3461 3494 * @since 4.5.0 3462 3495 * 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. 3464 3498 */ 3465 3499 public function close() { … … 3484 3518 3485 3519 /** 3486 * Whether MySQL database is at least the required minimum version.3520 * Determines whether MySQL database is at least the required minimum version. 3487 3521 * 3488 3522 * @since 2.5.0 3489 3523 * 3490 * @global string $wp_version 3491 * @global string $required_mysql_version 3492 * @return WP_Error|void3524 * @global string $wp_version The WordPress version string. 3525 * @global string $required_mysql_version The required MySQL version string. 3526 * @return void|WP_Error 3493 3527 */ 3494 3528 public function check_database_version() { … … 3502 3536 3503 3537 /** 3504 * Whether the database supports collation.3538 * Determines whether the database supports collation. 3505 3539 * 3506 3540 * Called when WordPress is generating the table scheme. … … 3511 3545 * @deprecated 3.5.0 Use wpdb::has_cap() 3512 3546 * 3513 * @return bool True if collation is supported, false if version does not3547 * @return bool True if collation is supported, false if not. 3514 3548 */ 3515 3549 public function supports_collation() { … … 3519 3553 3520 3554 /** 3521 * The database character collate.3555 * Retrieves the database character collate. 3522 3556 * 3523 3557 * @since 3.5.0 … … 3539 3573 3540 3574 /** 3541 * Determine if a database supports a particular feature.3575 * Determines if a database supports a particular feature. 3542 3576 * 3543 3577 * @since 2.7.0 … … 3547 3581 * @see wpdb::db_version() 3548 3582 * 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'. 3551 3585 * @return int|false Whether the database feature is supported, false otherwise. 3552 3586 */ … … 3589 3623 3590 3624 /** 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. 3594 3629 * 3595 3630 * @since 2.5.0 3596 3631 * 3597 * @return string Comma 3632 * @return string Comma-separated list of the calling functions. 3598 3633 */ 3599 3634 public function get_caller() {
Note:
See TracChangeset
for help on using the changeset viewer.
