| [ Index ] |
PHP Cross Reference of Joomla 4.2.2 documentation |
[Summary view] [Print] [Text view]
1 <?php 2 /** 3 * Part of the Joomla Framework String Package 4 * 5 * @copyright Copyright (C) 2005 - 2021 Open Source Matters, Inc. All rights reserved. 6 * @license GNU General Public License version 2 or later; see LICENSE 7 */ 8 9 namespace Joomla\String; 10 11 // PHP mbstring and iconv local configuration 12 @ini_set('default_charset', 'UTF-8'); 13 14 /** 15 * String handling class for UTF-8 data wrapping the phputf8 library. All functions assume the validity of UTF-8 strings. 16 * 17 * @since 1.3.0 18 */ 19 abstract class StringHelper 20 { 21 /** 22 * Increment styles. 23 * 24 * @var array 25 * @since 1.3.0 26 */ 27 protected static $incrementStyles = [ 28 'dash' => [ 29 '#-(\d+)$#', 30 '-%d', 31 ], 32 'default' => [ 33 ['#\((\d+)\)$#', '#\(\d+\)$#'], 34 [' (%d)', '(%d)'], 35 ], 36 ]; 37 38 /** 39 * Increments a trailing number in a string. 40 * 41 * Used to easily create distinct labels when copying objects. The method has the following styles: 42 * 43 * default: "Label" becomes "Label (2)" 44 * dash: "Label" becomes "Label-2" 45 * 46 * @param string $string The source string. 47 * @param string|null $style The the style (default|dash). 48 * @param integer $n If supplied, this number is used for the copy, otherwise it is the 'next' number. 49 * 50 * @return string The incremented string. 51 * 52 * @since 1.3.0 53 */ 54 public static function increment($string, $style = 'default', $n = 0) 55 { 56 $styleSpec = static::$incrementStyles[$style] ?? static::$incrementStyles['default']; 57 58 // Regular expression search and replace patterns. 59 if (\is_array($styleSpec[0])) 60 { 61 $rxSearch = $styleSpec[0][0]; 62 $rxReplace = $styleSpec[0][1]; 63 } 64 else 65 { 66 $rxSearch = $rxReplace = $styleSpec[0]; 67 } 68 69 // New and old (existing) sprintf formats. 70 if (\is_array($styleSpec[1])) 71 { 72 $newFormat = $styleSpec[1][0]; 73 $oldFormat = $styleSpec[1][1]; 74 } 75 else 76 { 77 $newFormat = $oldFormat = $styleSpec[1]; 78 } 79 80 // Check if we are incrementing an existing pattern, or appending a new one. 81 if (preg_match($rxSearch, $string, $matches)) 82 { 83 $n = empty($n) ? ($matches[1] + 1) : $n; 84 $string = preg_replace($rxReplace, sprintf($oldFormat, $n), $string); 85 } 86 else 87 { 88 $n = empty($n) ? 2 : $n; 89 $string .= sprintf($newFormat, $n); 90 } 91 92 return $string; 93 } 94 95 /** 96 * Tests whether a string contains only 7bit ASCII bytes. 97 * 98 * You might use this to conditionally check whether a string needs handling as UTF-8 or not, potentially offering performance 99 * benefits by using the native PHP equivalent if it's just ASCII e.g.; 100 * 101 * <code> 102 * if (StringHelper::is_ascii($someString)) 103 * { 104 * // It's just ASCII - use the native PHP version 105 * $someString = strtolower($someString); 106 * } 107 * else 108 * { 109 * $someString = StringHelper::strtolower($someString); 110 * } 111 * </code> 112 * 113 * @param string $str The string to test. 114 * 115 * @return boolean True if the string is all ASCII 116 * 117 * @since 1.3.0 118 */ 119 public static function is_ascii($str) 120 { 121 return utf8_is_ascii($str); 122 } 123 124 /** 125 * UTF-8 aware alternative to ord() 126 * 127 * Returns the unicode ordinal for a character. 128 * 129 * @param string $chr UTF-8 encoded character 130 * 131 * @return integer Unicode ordinal for the character 132 * 133 * @link https://www.php.net/ord 134 * @since 1.4.0 135 */ 136 public static function ord($chr) 137 { 138 return utf8_ord($chr); 139 } 140 141 /** 142 * UTF-8 aware alternative to strpos() 143 * 144 * Find position of first occurrence of a string. 145 * 146 * @param string $str String being examined 147 * @param string $search String being searched for 148 * @param integer|null|boolean $offset Optional, specifies the position from which the search should be performed 149 * 150 * @return integer|boolean Number of characters before the first match or FALSE on failure 151 * 152 * @link https://www.php.net/strpos 153 * @since 1.3.0 154 */ 155 public static function strpos($str, $search, $offset = false) 156 { 157 if ($offset === false) 158 { 159 return utf8_strpos($str, $search); 160 } 161 162 return utf8_strpos($str, $search, $offset); 163 } 164 165 /** 166 * UTF-8 aware alternative to strrpos() 167 * 168 * Finds position of last occurrence of a string. 169 * 170 * @param string $str String being examined. 171 * @param string $search String being searched for. 172 * @param integer $offset Offset from the left of the string. 173 * 174 * @return integer|boolean Number of characters before the last match or false on failure 175 * 176 * @link https://www.php.net/strrpos 177 * @since 1.3.0 178 */ 179 public static function strrpos($str, $search, $offset = 0) 180 { 181 return utf8_strrpos($str, $search, $offset); 182 } 183 184 /** 185 * UTF-8 aware alternative to substr() 186 * 187 * Return part of a string given character offset (and optionally length). 188 * 189 * @param string $str String being processed 190 * @param integer $offset Number of UTF-8 characters offset (from left) 191 * @param integer|null|boolean $length Optional length in UTF-8 characters from offset 192 * 193 * @return string|boolean 194 * 195 * @link https://www.php.net/substr 196 * @since 1.3.0 197 */ 198 public static function substr($str, $offset, $length = false) 199 { 200 if ($length === false) 201 { 202 return utf8_substr($str, $offset); 203 } 204 205 return utf8_substr($str, $offset, $length); 206 } 207 208 /** 209 * UTF-8 aware alternative to strtolower() 210 * 211 * Make a string lowercase 212 * 213 * Note: The concept of a characters "case" only exists is some alphabets such as Latin, Greek, Cyrillic, Armenian and archaic Georgian - it does 214 * not exist in the Chinese alphabet, for example. See Unicode Standard Annex #21: Case Mappings 215 * 216 * @param string $str String being processed 217 * 218 * @return string|boolean Either string in lowercase or FALSE is UTF-8 invalid 219 * 220 * @link https://www.php.net/strtolower 221 * @since 1.3.0 222 */ 223 public static function strtolower($str) 224 { 225 return utf8_strtolower($str); 226 } 227 228 /** 229 * UTF-8 aware alternative to strtoupper() 230 * 231 * Make a string uppercase 232 * 233 * Note: The concept of a characters "case" only exists is some alphabets such as Latin, Greek, Cyrillic, Armenian and archaic Georgian - it does 234 * not exist in the Chinese alphabet, for example. See Unicode Standard Annex #21: Case Mappings 235 * 236 * @param string $str String being processed 237 * 238 * @return string|boolean Either string in uppercase or FALSE is UTF-8 invalid 239 * 240 * @link https://www.php.net/strtoupper 241 * @since 1.3.0 242 */ 243 public static function strtoupper($str) 244 { 245 return utf8_strtoupper($str); 246 } 247 248 /** 249 * UTF-8 aware alternative to strlen() 250 * 251 * Returns the number of characters in the string (NOT THE NUMBER OF BYTES). 252 * 253 * @param string $str UTF-8 string. 254 * 255 * @return integer Number of UTF-8 characters in string. 256 * 257 * @link https://www.php.net/strlen 258 * @since 1.3.0 259 */ 260 public static function strlen($str) 261 { 262 return utf8_strlen($str); 263 } 264 265 /** 266 * UTF-8 aware alternative to str_ireplace() 267 * 268 * Case-insensitive version of str_replace() 269 * 270 * @param string $search String to search 271 * @param string $replace Existing string to replace 272 * @param string $str New string to replace with 273 * @param integer|null|boolean $count Optional count value to be passed by referene 274 * 275 * @return string UTF-8 String 276 * 277 * @link https://www.php.net/str_ireplace 278 * @since 1.3.0 279 */ 280 public static function str_ireplace($search, $replace, $str, $count = null) 281 { 282 if ($count === false) 283 { 284 return utf8_ireplace($search, $replace, $str); 285 } 286 287 return utf8_ireplace($search, $replace, $str, $count); 288 } 289 290 /** 291 * UTF-8 aware alternative to str_pad() 292 * 293 * Pad a string to a certain length with another string. 294 * $padStr may contain multi-byte characters. 295 * 296 * @param string $input The input string. 297 * @param integer $length If the value is negative, less than, or equal to the length of the input string, no padding takes place. 298 * @param string $padStr The string may be truncated if the number of padding characters can't be evenly divided by the string's length. 299 * @param integer $type The type of padding to apply 300 * 301 * @return string 302 * 303 * @link https://www.php.net/str_pad 304 * @since 1.4.0 305 */ 306 public static function str_pad($input, $length, $padStr = ' ', $type = STR_PAD_RIGHT) 307 { 308 return utf8_str_pad($input, $length, $padStr, $type); 309 } 310 311 /** 312 * UTF-8 aware alternative to str_split() 313 * 314 * Convert a string to an array. 315 * 316 * @param string $str UTF-8 encoded string to process 317 * @param integer $splitLen Number to characters to split string by 318 * 319 * @return array|string|boolean 320 * 321 * @link https://www.php.net/str_split 322 * @since 1.3.0 323 */ 324 public static function str_split($str, $splitLen = 1) 325 { 326 return utf8_str_split($str, $splitLen); 327 } 328 329 /** 330 * UTF-8/LOCALE aware alternative to strcasecmp() 331 * 332 * A case insensitive string comparison. 333 * 334 * @param string $str1 string 1 to compare 335 * @param string $str2 string 2 to compare 336 * @param string|boolean $locale The locale used by strcoll or false to use classical comparison 337 * 338 * @return integer < 0 if str1 is less than str2; > 0 if str1 is greater than str2, and 0 if they are equal. 339 * 340 * @link https://www.php.net/strcasecmp 341 * @link https://www.php.net/strcoll 342 * @link https://www.php.net/setlocale 343 * @since 1.3.0 344 */ 345 public static function strcasecmp($str1, $str2, $locale = false) 346 { 347 if ($locale === false) 348 { 349 return utf8_strcasecmp($str1, $str2); 350 } 351 352 // Get current locale 353 $locale0 = setlocale(LC_COLLATE, 0); 354 355 if (!$locale = setlocale(LC_COLLATE, $locale)) 356 { 357 $locale = $locale0; 358 } 359 360 // See if we have successfully set locale to UTF-8 361 if (!stristr($locale, 'UTF-8') && stristr($locale, '_') && preg_match('~\.(\d+)$~', $locale, $m)) 362 { 363 $encoding = 'CP' . $m[1]; 364 } 365 elseif (stristr($locale, 'UTF-8') || stristr($locale, 'utf8')) 366 { 367 $encoding = 'UTF-8'; 368 } 369 else 370 { 371 $encoding = 'nonrecodable'; 372 } 373 374 // If we successfully set encoding it to utf-8 or encoding is sth weird don't recode 375 if ($encoding == 'UTF-8' || $encoding == 'nonrecodable') 376 { 377 return strcoll(utf8_strtolower($str1), utf8_strtolower($str2)); 378 } 379 380 return strcoll( 381 static::transcode(utf8_strtolower($str1), 'UTF-8', $encoding), 382 static::transcode(utf8_strtolower($str2), 'UTF-8', $encoding) 383 ); 384 } 385 386 /** 387 * UTF-8/LOCALE aware alternative to strcmp() 388 * 389 * A case sensitive string comparison. 390 * 391 * @param string $str1 string 1 to compare 392 * @param string $str2 string 2 to compare 393 * @param mixed $locale The locale used by strcoll or false to use classical comparison 394 * 395 * @return integer < 0 if str1 is less than str2; > 0 if str1 is greater than str2, and 0 if they are equal. 396 * 397 * @link https://www.php.net/strcmp 398 * @link https://www.php.net/strcoll 399 * @link https://www.php.net/setlocale 400 * @since 1.3.0 401 */ 402 public static function strcmp($str1, $str2, $locale = false) 403 { 404 if ($locale) 405 { 406 // Get current locale 407 $locale0 = setlocale(LC_COLLATE, 0); 408 409 if (!$locale = setlocale(LC_COLLATE, $locale)) 410 { 411 $locale = $locale0; 412 } 413 414 // See if we have successfully set locale to UTF-8 415 if (!stristr($locale, 'UTF-8') && stristr($locale, '_') && preg_match('~\.(\d+)$~', $locale, $m)) 416 { 417 $encoding = 'CP' . $m[1]; 418 } 419 elseif (stristr($locale, 'UTF-8') || stristr($locale, 'utf8')) 420 { 421 $encoding = 'UTF-8'; 422 } 423 else 424 { 425 $encoding = 'nonrecodable'; 426 } 427 428 // If we successfully set encoding it to utf-8 or encoding is sth weird don't recode 429 if ($encoding == 'UTF-8' || $encoding == 'nonrecodable') 430 { 431 return strcoll($str1, $str2); 432 } 433 434 return strcoll(static::transcode($str1, 'UTF-8', $encoding), static::transcode($str2, 'UTF-8', $encoding)); 435 } 436 437 return strcmp($str1, $str2); 438 } 439 440 /** 441 * UTF-8 aware alternative to strcspn() 442 * 443 * Find length of initial segment not matching mask. 444 * 445 * @param string $str The string to process 446 * @param string $mask The mask 447 * @param integer|boolean $start Optional starting character position (in characters) 448 * @param integer|boolean $length Optional length 449 * 450 * @return integer The length of the initial segment of str1 which does not contain any of the characters in str2 451 * 452 * @link https://www.php.net/strcspn 453 * @since 1.3.0 454 */ 455 public static function strcspn($str, $mask, $start = null, $length = null) 456 { 457 if ($start === false && $length === false) 458 { 459 return utf8_strcspn($str, $mask); 460 } 461 462 if ($length === false) 463 { 464 return utf8_strcspn($str, $mask, $start); 465 } 466 467 return utf8_strcspn($str, $mask, $start, $length); 468 } 469 470 /** 471 * UTF-8 aware alternative to stristr() 472 * 473 * Returns all of haystack from the first occurrence of needle to the end. Needle and haystack are examined in a case-insensitive manner to 474 * find the first occurrence of a string using case insensitive comparison. 475 * 476 * @param string $str The haystack 477 * @param string $search The needle 478 * 479 * @return string|boolean 480 * 481 * @link https://www.php.net/stristr 482 * @since 1.3.0 483 */ 484 public static function stristr($str, $search) 485 { 486 return utf8_stristr($str, $search); 487 } 488 489 /** 490 * UTF-8 aware alternative to strrev() 491 * 492 * Reverse a string. 493 * 494 * @param string $str String to be reversed 495 * 496 * @return string The string in reverse character order 497 * 498 * @link https://www.php.net/strrev 499 * @since 1.3.0 500 */ 501 public static function strrev($str) 502 { 503 return utf8_strrev($str); 504 } 505 506 /** 507 * UTF-8 aware alternative to strspn() 508 * 509 * Find length of initial segment matching mask. 510 * 511 * @param string $str The haystack 512 * @param string $mask The mask 513 * @param integer|null $start Start optional 514 * @param integer|null $length Length optional 515 * 516 * @return integer 517 * 518 * @link https://www.php.net/strspn 519 * @since 1.3.0 520 */ 521 public static function strspn($str, $mask, $start = null, $length = null) 522 { 523 if ($start === null && $length === null) 524 { 525 return utf8_strspn($str, $mask); 526 } 527 528 if ($length === null) 529 { 530 return utf8_strspn($str, $mask, $start); 531 } 532 533 return utf8_strspn($str, $mask, $start, $length); 534 } 535 536 /** 537 * UTF-8 aware alternative to substr_replace() 538 * 539 * Replace text within a portion of a string. 540 * 541 * @param string $str The haystack 542 * @param string $repl The replacement string 543 * @param integer $start Start 544 * @param integer|boolean|null $length Length (optional) 545 * 546 * @return string 547 * 548 * @link https://www.php.net/substr_replace 549 * @since 1.3.0 550 */ 551 public static function substr_replace($str, $repl, $start, $length = null) 552 { 553 // Loaded by library loader 554 if ($length === false) 555 { 556 return utf8_substr_replace($str, $repl, $start); 557 } 558 559 return utf8_substr_replace($str, $repl, $start, $length); 560 } 561 562 /** 563 * UTF-8 aware replacement for ltrim() 564 * 565 * Strip whitespace (or other characters) from the beginning of a string. You only need to use this if you are supplying the charlist 566 * optional arg and it contains UTF-8 characters. Otherwise ltrim will work normally on a UTF-8 string. 567 * 568 * @param string $str The string to be trimmed 569 * @param string|boolean $charlist The optional charlist of additional characters to trim 570 * 571 * @return string The trimmed string 572 * 573 * @link https://www.php.net/ltrim 574 * @since 1.3.0 575 */ 576 public static function ltrim($str, $charlist = false) 577 { 578 if (empty($charlist) && $charlist !== false) 579 { 580 return $str; 581 } 582 583 if ($charlist === false) 584 { 585 return utf8_ltrim($str); 586 } 587 588 return utf8_ltrim($str, $charlist); 589 } 590 591 /** 592 * UTF-8 aware replacement for rtrim() 593 * 594 * Strip whitespace (or other characters) from the end of a string. You only need to use this if you are supplying the charlist 595 * optional arg and it contains UTF-8 characters. Otherwise rtrim will work normally on a UTF-8 string. 596 * 597 * @param string $str The string to be trimmed 598 * @param string|boolean $charlist The optional charlist of additional characters to trim 599 * 600 * @return string The trimmed string 601 * 602 * @link https://www.php.net/rtrim 603 * @since 1.3.0 604 */ 605 public static function rtrim($str, $charlist = false) 606 { 607 if (empty($charlist) && $charlist !== false) 608 { 609 return $str; 610 } 611 612 if ($charlist === false) 613 { 614 return utf8_rtrim($str); 615 } 616 617 return utf8_rtrim($str, $charlist); 618 } 619 620 /** 621 * UTF-8 aware replacement for trim() 622 * 623 * Strip whitespace (or other characters) from the beginning and end of a string. You only need to use this if you are supplying the charlist 624 * optional arg and it contains UTF-8 characters. Otherwise trim will work normally on a UTF-8 string 625 * 626 * @param string $str The string to be trimmed 627 * @param string|boolean $charlist The optional charlist of additional characters to trim 628 * 629 * @return string The trimmed string 630 * 631 * @link https://www.php.net/trim 632 * @since 1.3.0 633 */ 634 public static function trim($str, $charlist = false) 635 { 636 if (empty($charlist) && $charlist !== false) 637 { 638 return $str; 639 } 640 641 if ($charlist === false) 642 { 643 return utf8_trim($str); 644 } 645 646 return utf8_trim($str, $charlist); 647 } 648 649 /** 650 * UTF-8 aware alternative to ucfirst() 651 * 652 * Make a string's first character uppercase or all words' first character uppercase. 653 * 654 * @param string $str String to be processed 655 * @param string|null $delimiter The words delimiter (null means do not split the string) 656 * @param string|null $newDelimiter The new words delimiter (null means equal to $delimiter) 657 * 658 * @return string If $delimiter is null, return the string with first character as upper case (if applicable) 659 * else consider the string of words separated by the delimiter, apply the ucfirst to each words 660 * and return the string with the new delimiter 661 * 662 * @link https://www.php.net/ucfirst 663 * @since 1.3.0 664 */ 665 public static function ucfirst($str, $delimiter = null, $newDelimiter = null) 666 { 667 if ($delimiter === null) 668 { 669 return utf8_ucfirst($str); 670 } 671 672 if ($newDelimiter === null) 673 { 674 $newDelimiter = $delimiter; 675 } 676 677 return implode($newDelimiter, array_map('utf8_ucfirst', explode($delimiter, $str))); 678 } 679 680 /** 681 * UTF-8 aware alternative to ucwords() 682 * 683 * Uppercase the first character of each word in a string. 684 * 685 * @param string $str String to be processed 686 * 687 * @return string String with first char of each word uppercase 688 * 689 * @link https://www.php.net/ucwords 690 * @since 1.3.0 691 */ 692 public static function ucwords($str) 693 { 694 return utf8_ucwords($str); 695 } 696 697 /** 698 * Transcode a string. 699 * 700 * @param string $source The string to transcode. 701 * @param string $fromEncoding The source encoding. 702 * @param string $toEncoding The target encoding. 703 * 704 * @return string|null The transcoded string, or null if the source was not a string. 705 * 706 * @link https://bugs.php.net/bug.php?id=48147 707 * 708 * @since 1.3.0 709 */ 710 public static function transcode($source, $fromEncoding, $toEncoding) 711 { 712 switch (ICONV_IMPL) 713 { 714 case 'glibc': 715 return @iconv($fromEncoding, $toEncoding . '//TRANSLIT,IGNORE', $source); 716 717 case 'libiconv': 718 default: 719 return iconv($fromEncoding, $toEncoding . '//IGNORE//TRANSLIT', $source); 720 } 721 } 722 723 /** 724 * Tests a string as to whether it's valid UTF-8 and supported by the Unicode standard. 725 * 726 * Note: this function has been modified to simple return true or false. 727 * 728 * @param string $str UTF-8 encoded string. 729 * 730 * @return boolean true if valid 731 * 732 * @author <[email protected]> 733 * @link https://hsivonen.fi/php-utf8/ 734 * @see compliant 735 * @since 1.3.0 736 */ 737 public static function valid($str) 738 { 739 return utf8_is_valid($str); 740 } 741 742 /** 743 * Tests whether a string complies as UTF-8. 744 * 745 * This will be much faster than StringHelper::valid() but will pass five and six octet UTF-8 sequences, which are not supported by Unicode and 746 * so cannot be displayed correctly in a browser. In other words it is not as strict as StringHelper::valid() but it's faster. If you use it to 747 * validate user input, you place yourself at the risk that attackers will be able to inject 5 and 6 byte sequences (which may or may not be a 748 * significant risk, depending on what you are are doing). 749 * 750 * @param string $str UTF-8 string to check 751 * 752 * @return boolean TRUE if string is valid UTF-8 753 * 754 * @see StringHelper::valid 755 * @link https://www.php.net/manual/en/reference.pcre.pattern.modifiers.php#54805 756 * @since 1.3.0 757 */ 758 public static function compliant($str) 759 { 760 return utf8_compliant($str); 761 } 762 763 /** 764 * Converts Unicode sequences to UTF-8 string. 765 * 766 * @param string $str Unicode string to convert 767 * 768 * @return string UTF-8 string 769 * 770 * @since 1.3.0 771 */ 772 public static function unicode_to_utf8($str) 773 { 774 if (\extension_loaded('mbstring')) 775 { 776 return preg_replace_callback( 777 '/\\\\u([0-9a-fA-F]{4})/', 778 static function ($match) 779 { 780 return mb_convert_encoding(pack('H*', $match[1]), 'UTF-8', 'UCS-2BE'); 781 }, 782 $str 783 ); 784 } 785 786 return $str; 787 } 788 789 /** 790 * Converts Unicode sequences to UTF-16 string. 791 * 792 * @param string $str Unicode string to convert 793 * 794 * @return string UTF-16 string 795 * 796 * @since 1.3.0 797 */ 798 public static function unicode_to_utf16($str) 799 { 800 if (\extension_loaded('mbstring')) 801 { 802 return preg_replace_callback( 803 '/\\\\u([0-9a-fA-F]{4})/', 804 static function ($match) 805 { 806 return mb_convert_encoding(pack('H*', $match[1]), 'UTF-8', 'UTF-16BE'); 807 }, 808 $str 809 ); 810 } 811 812 return $str; 813 } 814 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated: Wed Sep 7 05:41:13 2022 | Chilli.vc Blog - For Webmaster,Blog-Writer,System Admin and Domainer |