| [ Index ] |
PHP Cross Reference of WordPress Trunk (Updated Daily) |
[Summary view] [Print] [Text view]
1 <?php 2 /** 3 * WordPress implementation for PHP functions either missing from older PHP versions or not included by default. 4 * 5 * This file is loaded extremely early and the functions can be relied upon by drop-ins. 6 * Ergo, please ensure you do not rely on external functions when writing code for this file. 7 * Only use functions built into PHP or are defined in this file and have adequate testing 8 * and error suppression to ensure the file will run correctly and not break websites. 9 * 10 * @package PHP 11 * @access private 12 */ 13 14 // If gettext isn't available. 15 if ( ! function_exists( '_' ) ) { 16 function _( $message ) { 17 return $message; 18 } 19 } 20 21 /** 22 * Returns whether PCRE/u (PCRE_UTF8 modifier) is available for use. 23 * 24 * @ignore 25 * @since 4.2.2 26 * @access private 27 * 28 * @param bool $set - Used for testing only 29 * null : default - get PCRE/u capability 30 * false : Used for testing - return false for future calls to this function 31 * 'reset': Used for testing - restore default behavior of this function 32 */ 33 function _wp_can_use_pcre_u( $set = null ) { 34 static $utf8_pcre = 'reset'; 35 36 if ( null !== $set ) { 37 $utf8_pcre = $set; 38 } 39 40 if ( 'reset' === $utf8_pcre ) { 41 // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged -- intentional error generated to detect PCRE/u support. 42 $utf8_pcre = @preg_match( '/^./u', 'a' ); 43 } 44 45 return $utf8_pcre; 46 } 47 48 /** 49 * Indicates if a given slug for a character set represents the UTF-8 text encoding. 50 * 51 * A charset is considered to represent UTF-8 if it is a case-insensitive match 52 * of "UTF-8" with or without the hyphen. 53 * 54 * Example: 55 * 56 * true === _is_utf8_charset( 'UTF-8' ); 57 * true === _is_utf8_charset( 'utf8' ); 58 * false === _is_utf8_charset( 'latin1' ); 59 * false === _is_utf8_charset( 'UTF 8' ); 60 * 61 * // Only strings match. 62 * false === _is_utf8_charset( [ 'charset' => 'utf-8' ] ); 63 * 64 * `is_utf8_charset` should be used outside of this file. 65 * 66 * @ignore 67 * @since 6.6.1 68 * 69 * @param string $charset_slug Slug representing a text character encoding, or "charset". 70 * E.g. "UTF-8", "Windows-1252", "ISO-8859-1", "SJIS". 71 * 72 * @return bool Whether the slug represents the UTF-8 encoding. 73 */ 74 function _is_utf8_charset( $charset_slug ) { 75 if ( ! is_string( $charset_slug ) ) { 76 return false; 77 } 78 79 return ( 80 0 === strcasecmp( 'UTF-8', $charset_slug ) || 81 0 === strcasecmp( 'UTF8', $charset_slug ) 82 ); 83 } 84 85 if ( ! function_exists( 'mb_substr' ) ) : 86 /** 87 * Compat function to mimic mb_substr(). 88 * 89 * @ignore 90 * @since 3.2.0 91 * 92 * @see _mb_substr() 93 * 94 * @param string $string The string to extract the substring from. 95 * @param int $start Position to being extraction from in `$string`. 96 * @param int|null $length Optional. Maximum number of characters to extract from `$string`. 97 * Default null. 98 * @param string|null $encoding Optional. Character encoding to use. Default null. 99 * @return string Extracted substring. 100 */ 101 function mb_substr( $string, $start, $length = null, $encoding = null ) { // phpcs:ignore Universal.NamingConventions.NoReservedKeywordParameterNames.stringFound 102 return _mb_substr( $string, $start, $length, $encoding ); 103 } 104 endif; 105 106 /** 107 * Internal compat function to mimic mb_substr(). 108 * 109 * Only understands UTF-8 and 8bit. All other character sets will be treated as 8bit. 110 * For `$encoding === UTF-8`, the `$str` input is expected to be a valid UTF-8 byte 111 * sequence. The behavior of this function for invalid inputs is undefined. 112 * 113 * @ignore 114 * @since 3.2.0 115 * 116 * @param string $str The string to extract the substring from. 117 * @param int $start Position to being extraction from in `$str`. 118 * @param int|null $length Optional. Maximum number of characters to extract from `$str`. 119 * Default null. 120 * @param string|null $encoding Optional. Character encoding to use. Default null. 121 * @return string Extracted substring. 122 */ 123 function _mb_substr( $str, $start, $length = null, $encoding = null ) { 124 if ( null === $str ) { 125 return ''; 126 } 127 128 if ( null === $encoding ) { 129 $encoding = get_option( 'blog_charset' ); 130 } 131 132 /* 133 * The solution below works only for UTF-8, so in case of a different 134 * charset just use built-in substr(). 135 */ 136 if ( ! _is_utf8_charset( $encoding ) ) { 137 return is_null( $length ) ? substr( $str, $start ) : substr( $str, $start, $length ); 138 } 139 140 if ( _wp_can_use_pcre_u() ) { 141 // Use the regex unicode support to separate the UTF-8 characters into an array. 142 preg_match_all( '/./us', $str, $match ); 143 $chars = is_null( $length ) ? array_slice( $match[0], $start ) : array_slice( $match[0], $start, $length ); 144 return implode( '', $chars ); 145 } 146 147 $regex = '/( 148 [\x00-\x7F] # single-byte sequences 0xxxxxxx 149 | [\xC2-\xDF][\x80-\xBF] # double-byte sequences 110xxxxx 10xxxxxx 150 | \xE0[\xA0-\xBF][\x80-\xBF] # triple-byte sequences 1110xxxx 10xxxxxx * 2 151 | [\xE1-\xEC][\x80-\xBF]{2} 152 | \xED[\x80-\x9F][\x80-\xBF] 153 | [\xEE-\xEF][\x80-\xBF]{2} 154 | \xF0[\x90-\xBF][\x80-\xBF]{2} # four-byte sequences 11110xxx 10xxxxxx * 3 155 | [\xF1-\xF3][\x80-\xBF]{3} 156 | \xF4[\x80-\x8F][\x80-\xBF]{2} 157 )/x'; 158 159 // Start with 1 element instead of 0 since the first thing we do is pop. 160 $chars = array( '' ); 161 162 do { 163 // We had some string left over from the last round, but we counted it in that last round. 164 array_pop( $chars ); 165 166 /* 167 * Split by UTF-8 character, limit to 1000 characters (last array element will contain 168 * the rest of the string). 169 */ 170 $pieces = preg_split( $regex, $str, 1000, PREG_SPLIT_DELIM_CAPTURE | PREG_SPLIT_NO_EMPTY ); 171 172 $chars = array_merge( $chars, $pieces ); 173 174 // If there's anything left over, repeat the loop. 175 } while ( count( $pieces ) > 1 && $str = array_pop( $pieces ) ); 176 177 return implode( '', array_slice( $chars, $start, $length ) ); 178 } 179 180 if ( ! function_exists( 'mb_strlen' ) ) : 181 /** 182 * Compat function to mimic mb_strlen(). 183 * 184 * @ignore 185 * @since 4.2.0 186 * 187 * @see _mb_strlen() 188 * 189 * @param string $string The string to retrieve the character length from. 190 * @param string|null $encoding Optional. Character encoding to use. Default null. 191 * @return int String length of `$string`. 192 */ 193 function mb_strlen( $string, $encoding = null ) { // phpcs:ignore Universal.NamingConventions.NoReservedKeywordParameterNames.stringFound 194 return _mb_strlen( $string, $encoding ); 195 } 196 endif; 197 198 /** 199 * Internal compat function to mimic mb_strlen(). 200 * 201 * Only understands UTF-8 and 8bit. All other character sets will be treated as 8bit. 202 * For `$encoding === UTF-8`, the `$str` input is expected to be a valid UTF-8 byte 203 * sequence. The behavior of this function for invalid inputs is undefined. 204 * 205 * @ignore 206 * @since 4.2.0 207 * 208 * @param string $str The string to retrieve the character length from. 209 * @param string|null $encoding Optional. Character encoding to use. Default null. 210 * @return int String length of `$str`. 211 */ 212 function _mb_strlen( $str, $encoding = null ) { 213 if ( null === $encoding ) { 214 $encoding = get_option( 'blog_charset' ); 215 } 216 217 /* 218 * The solution below works only for UTF-8, so in case of a different charset 219 * just use built-in strlen(). 220 */ 221 if ( ! _is_utf8_charset( $encoding ) ) { 222 return strlen( $str ); 223 } 224 225 if ( _wp_can_use_pcre_u() ) { 226 // Use the regex unicode support to separate the UTF-8 characters into an array. 227 preg_match_all( '/./us', $str, $match ); 228 return count( $match[0] ); 229 } 230 231 $regex = '/(?: 232 [\x00-\x7F] # single-byte sequences 0xxxxxxx 233 | [\xC2-\xDF][\x80-\xBF] # double-byte sequences 110xxxxx 10xxxxxx 234 | \xE0[\xA0-\xBF][\x80-\xBF] # triple-byte sequences 1110xxxx 10xxxxxx * 2 235 | [\xE1-\xEC][\x80-\xBF]{2} 236 | \xED[\x80-\x9F][\x80-\xBF] 237 | [\xEE-\xEF][\x80-\xBF]{2} 238 | \xF0[\x90-\xBF][\x80-\xBF]{2} # four-byte sequences 11110xxx 10xxxxxx * 3 239 | [\xF1-\xF3][\x80-\xBF]{3} 240 | \xF4[\x80-\x8F][\x80-\xBF]{2} 241 )/x'; 242 243 // Start at 1 instead of 0 since the first thing we do is decrement. 244 $count = 1; 245 246 do { 247 // We had some string left over from the last round, but we counted it in that last round. 248 --$count; 249 250 /* 251 * Split by UTF-8 character, limit to 1000 characters (last array element will contain 252 * the rest of the string). 253 */ 254 $pieces = preg_split( $regex, $str, 1000 ); 255 256 // Increment. 257 $count += count( $pieces ); 258 259 // If there's anything left over, repeat the loop. 260 } while ( $str = array_pop( $pieces ) ); 261 262 // Fencepost: preg_split() always returns one extra item in the array. 263 return --$count; 264 } 265 266 if ( ! function_exists( 'hash_hmac' ) ) : 267 /** 268 * Compat function to mimic hash_hmac(). 269 * 270 * The Hash extension is bundled with PHP by default since PHP 5.1.2. 271 * However, the extension may be explicitly disabled on select servers. 272 * As of PHP 7.4.0, the Hash extension is a core PHP extension and can no 273 * longer be disabled. 274 * I.e. when PHP 7.4.0 becomes the minimum requirement, this polyfill 275 * and the associated `_hash_hmac()` function can be safely removed. 276 * 277 * @ignore 278 * @since 3.2.0 279 * 280 * @see _hash_hmac() 281 * 282 * @param string $algo Hash algorithm. Accepts 'md5' or 'sha1'. 283 * @param string $data Data to be hashed. 284 * @param string $key Secret key to use for generating the hash. 285 * @param bool $binary Optional. Whether to output raw binary data (true), 286 * or lowercase hexits (false). Default false. 287 * @return string|false The hash in output determined by `$binary`. 288 * False if `$algo` is unknown or invalid. 289 */ 290 function hash_hmac( $algo, $data, $key, $binary = false ) { 291 return _hash_hmac( $algo, $data, $key, $binary ); 292 } 293 endif; 294 295 /** 296 * Internal compat function to mimic hash_hmac(). 297 * 298 * @ignore 299 * @since 3.2.0 300 * 301 * @param string $algo Hash algorithm. Accepts 'md5' or 'sha1'. 302 * @param string $data Data to be hashed. 303 * @param string $key Secret key to use for generating the hash. 304 * @param bool $binary Optional. Whether to output raw binary data (true), 305 * or lowercase hexits (false). Default false. 306 * @return string|false The hash in output determined by `$binary`. 307 * False if `$algo` is unknown or invalid. 308 */ 309 function _hash_hmac( $algo, $data, $key, $binary = false ) { 310 $packs = array( 311 'md5' => 'H32', 312 'sha1' => 'H40', 313 ); 314 315 if ( ! isset( $packs[ $algo ] ) ) { 316 return false; 317 } 318 319 $pack = $packs[ $algo ]; 320 321 if ( strlen( $key ) > 64 ) { 322 $key = pack( $pack, $algo( $key ) ); 323 } 324 325 $key = str_pad( $key, 64, chr( 0 ) ); 326 327 $ipad = ( substr( $key, 0, 64 ) ^ str_repeat( chr( 0x36 ), 64 ) ); 328 $opad = ( substr( $key, 0, 64 ) ^ str_repeat( chr( 0x5C ), 64 ) ); 329 330 $hmac = $algo( $opad . pack( $pack, $algo( $ipad . $data ) ) ); 331 332 if ( $binary ) { 333 return pack( $pack, $hmac ); 334 } 335 336 return $hmac; 337 } 338 339 if ( ! function_exists( 'hash_equals' ) ) : 340 /** 341 * Timing attack safe string comparison. 342 * 343 * Compares two strings using the same time whether they're equal or not. 344 * 345 * Note: It can leak the length of a string when arguments of differing length are supplied. 346 * 347 * This function was added in PHP 5.6. 348 * However, the Hash extension may be explicitly disabled on select servers. 349 * As of PHP 7.4.0, the Hash extension is a core PHP extension and can no 350 * longer be disabled. 351 * I.e. when PHP 7.4.0 becomes the minimum requirement, this polyfill 352 * can be safely removed. 353 * 354 * @since 3.9.2 355 * 356 * @param string $known_string Expected string. 357 * @param string $user_string Actual, user supplied, string. 358 * @return bool Whether strings are equal. 359 */ 360 function hash_equals( $known_string, $user_string ) { 361 $known_string_length = strlen( $known_string ); 362 363 if ( strlen( $user_string ) !== $known_string_length ) { 364 return false; 365 } 366 367 $result = 0; 368 369 // Do not attempt to "optimize" this. 370 for ( $i = 0; $i < $known_string_length; $i++ ) { 371 $result |= ord( $known_string[ $i ] ) ^ ord( $user_string[ $i ] ); 372 } 373 374 return 0 === $result; 375 } 376 endif; 377 378 // sodium_crypto_box() was introduced in PHP 7.2. 379 if ( ! function_exists( 'sodium_crypto_box' ) ) { 380 require ABSPATH . WPINC . '/sodium_compat/autoload.php'; 381 } 382 383 if ( ! function_exists( 'is_countable' ) ) { 384 /** 385 * Polyfill for is_countable() function added in PHP 7.3. 386 * 387 * Verify that the content of a variable is an array or an object 388 * implementing the Countable interface. 389 * 390 * @since 4.9.6 391 * 392 * @param mixed $value The value to check. 393 * @return bool True if `$value` is countable, false otherwise. 394 */ 395 function is_countable( $value ) { 396 return ( is_array( $value ) 397 || $value instanceof Countable 398 || $value instanceof SimpleXMLElement 399 || $value instanceof ResourceBundle 400 ); 401 } 402 } 403 404 if ( ! function_exists( 'array_key_first' ) ) { 405 /** 406 * Polyfill for array_key_first() function added in PHP 7.3. 407 * 408 * Get the first key of the given array without affecting 409 * the internal array pointer. 410 * 411 * @since 5.9.0 412 * 413 * @param array $array An array. 414 * @return string|int|null The first key of array if the array 415 * is not empty; `null` otherwise. 416 */ 417 function array_key_first( array $array ) { // phpcs:ignore Universal.NamingConventions.NoReservedKeywordParameterNames.arrayFound 418 foreach ( $array as $key => $value ) { 419 return $key; 420 } 421 } 422 } 423 424 if ( ! function_exists( 'array_key_last' ) ) { 425 /** 426 * Polyfill for `array_key_last()` function added in PHP 7.3. 427 * 428 * Get the last key of the given array without affecting the 429 * internal array pointer. 430 * 431 * @since 5.9.0 432 * 433 * @param array $array An array. 434 * @return string|int|null The last key of array if the array 435 *. is not empty; `null` otherwise. 436 */ 437 function array_key_last( array $array ) { // phpcs:ignore Universal.NamingConventions.NoReservedKeywordParameterNames.arrayFound 438 if ( empty( $array ) ) { 439 return null; 440 } 441 442 end( $array ); 443 444 return key( $array ); 445 } 446 } 447 448 if ( ! function_exists( 'array_is_list' ) ) { 449 /** 450 * Polyfill for `array_is_list()` function added in PHP 8.1. 451 * 452 * Determines if the given array is a list. 453 * 454 * An array is considered a list if its keys consist of consecutive numbers from 0 to count($array)-1. 455 * 456 * @see https://github.com/symfony/polyfill-php81/tree/main 457 * 458 * @since 6.5.0 459 * 460 * @param array<mixed> $arr The array being evaluated. 461 * @return bool True if array is a list, false otherwise. 462 */ 463 function array_is_list( $arr ) { 464 if ( ( array() === $arr ) || ( array_values( $arr ) === $arr ) ) { 465 return true; 466 } 467 468 $next_key = -1; 469 470 foreach ( $arr as $k => $v ) { 471 if ( ++$next_key !== $k ) { 472 return false; 473 } 474 } 475 476 return true; 477 } 478 } 479 480 if ( ! function_exists( 'str_contains' ) ) { 481 /** 482 * Polyfill for `str_contains()` function added in PHP 8.0. 483 * 484 * Performs a case-sensitive check indicating if needle is 485 * contained in haystack. 486 * 487 * @since 5.9.0 488 * 489 * @param string $haystack The string to search in. 490 * @param string $needle The substring to search for in the `$haystack`. 491 * @return bool True if `$needle` is in `$haystack`, otherwise false. 492 */ 493 function str_contains( $haystack, $needle ) { 494 if ( '' === $needle ) { 495 return true; 496 } 497 498 return false !== strpos( $haystack, $needle ); 499 } 500 } 501 502 if ( ! function_exists( 'str_starts_with' ) ) { 503 /** 504 * Polyfill for `str_starts_with()` function added in PHP 8.0. 505 * 506 * Performs a case-sensitive check indicating if 507 * the haystack begins with needle. 508 * 509 * @since 5.9.0 510 * 511 * @param string $haystack The string to search in. 512 * @param string $needle The substring to search for in the `$haystack`. 513 * @return bool True if `$haystack` starts with `$needle`, otherwise false. 514 */ 515 function str_starts_with( $haystack, $needle ) { 516 if ( '' === $needle ) { 517 return true; 518 } 519 520 return 0 === strpos( $haystack, $needle ); 521 } 522 } 523 524 if ( ! function_exists( 'str_ends_with' ) ) { 525 /** 526 * Polyfill for `str_ends_with()` function added in PHP 8.0. 527 * 528 * Performs a case-sensitive check indicating if 529 * the haystack ends with needle. 530 * 531 * @since 5.9.0 532 * 533 * @param string $haystack The string to search in. 534 * @param string $needle The substring to search for in the `$haystack`. 535 * @return bool True if `$haystack` ends with `$needle`, otherwise false. 536 */ 537 function str_ends_with( $haystack, $needle ) { 538 if ( '' === $haystack ) { 539 return '' === $needle; 540 } 541 542 $len = strlen( $needle ); 543 544 return substr( $haystack, -$len, $len ) === $needle; 545 } 546 } 547 548 // IMAGETYPE_AVIF constant is only defined in PHP 8.x or later. 549 if ( ! defined( 'IMAGETYPE_AVIF' ) ) { 550 define( 'IMAGETYPE_AVIF', 19 ); 551 } 552 553 // IMG_AVIF constant is only defined in PHP 8.x or later. 554 if ( ! defined( 'IMG_AVIF' ) ) { 555 define( 'IMG_AVIF', IMAGETYPE_AVIF ); 556 } 557 558 // IMAGETYPE_HEIC constant is not yet defined in PHP as of PHP 8.3. 559 if ( ! defined( 'IMAGETYPE_HEIC' ) ) { 560 define( 'IMAGETYPE_HEIC', 99 ); 561 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated : Thu Nov 21 08:20:01 2024 | Cross-referenced by PHPXref |