\mb_substr($haystack, $offset, $length, $encoding); } } if ( $encoding !== 'UTF-8' && self::$SUPPORT['mbstring'] === false ) { /** * @psalm-suppress ImpureFunctionCall - this is only a warning */ \trigger_error('UTF8::substr_count() without mbstring cannot handle "' . $encoding . '" encoding', \E_USER_WARNING); } if (self::$SUPPORT['mbstring'] === true) { if ($encoding === 'UTF-8') { return \mb_substr_count($haystack, $needle); } return \mb_substr_count($haystack, $needle, $encoding); } \preg_match_all('/' . \preg_quote($needle, '/') . '/us', $haystack, $matches, \PREG_SET_ORDER); return \count($matches); } /** * Count the number of substring occurrences. * * @param string $haystack
* The string being checked. *
* @param string $needle* The string being found. *
* @param int $offset [optional]* The offset where to start counting *
* @param int|null $length [optional]* The maximum length after the specified offset to search for the * substring. It outputs a warning if the offset plus the length is * greater than the haystack length. *
* * @psalm-pure * * @return false|int *The number of times the * needle substring occurs in the * haystack string.
*/ public static function substr_count_in_byte( string $haystack, string $needle, int $offset = 0, int $length = null ) { if ($haystack === '' || $needle === '') { return 0; } if ( ($offset || $length !== null) && self::$SUPPORT['mbstring_func_overload'] === true ) { if ($length === null) { $length_tmp = self::strlen($haystack); if ($length_tmp === false) { return false; } $length = $length_tmp; } if ( ( $length !== 0 && $offset !== 0 ) && ($length + $offset) <= 0 && \PHP_VERSION_ID < 71000 // output from "substr_count()" have changed in PHP 7.1 ) { return false; } /** @var false|string $haystack_tmp - needed for PhpStan (stubs error) */ $haystack_tmp = \substr($haystack, $offset, $length); if ($haystack_tmp === false) { $haystack_tmp = ''; } $haystack = (string) $haystack_tmp; } if (self::$SUPPORT['mbstring_func_overload'] === true) { // "mb_" is available if overload is used, so use it ... return \mb_substr_count($haystack, $needle, 'CP850'); // 8-BIT } if ($length === null) { return \substr_count($haystack, $needle, $offset); } return \substr_count($haystack, $needle, $offset, $length); } /** * Returns the number of occurrences of $substring in the given string. * By default, the comparison is case-sensitive, but can be made insensitive * by setting $case_sensitive to false. * * @param string $strThe input string.
* @param string $substringThe substring to search for.
* @param bool $case_sensitive [optional]Whether or not to enforce case-sensitivity. Default: true
* @param string $encoding [optional]Set the charset for e.g. "mb_" function
* * @psalm-pure * * @return int * * @phpstan-return 0|positive-int */ public static function substr_count_simple( string $str, string $substring, bool $case_sensitive = true, string $encoding = 'UTF-8' ): int { if ($str === '' || $substring === '') { return 0; } if ($encoding === 'UTF-8') { if ($case_sensitive) { return (int) \mb_substr_count($str, $substring); } return (int) \mb_substr_count( \mb_strtoupper($str), \mb_strtoupper($substring) ); } $encoding = self::normalize_encoding($encoding, 'UTF-8'); if ($case_sensitive) { return (int) \mb_substr_count($str, $substring, $encoding); } return (int) \mb_substr_count( self::strtocasefold($str, true, false, $encoding, null, false), self::strtocasefold($substring, true, false, $encoding, null, false), $encoding ); } /** * Removes a prefix ($needle) from the beginning of the string ($haystack), case-insensitive. * * EXMAPLE:
* UTF8::substr_ileft('ΚόσμεMiddleEnd', 'Κόσμε'); // 'MiddleEnd'
* UTF8::substr_ileft('ΚόσμεMiddleEnd', 'κόσμε'); // 'MiddleEnd'
*
*
* @param string $haystack The string to search in.
* @param string $needleThe substring to search for.
* * @psalm-pure * * @return string *Return the sub-string.
*/ public static function substr_ileft(string $haystack, string $needle): string { if ($haystack === '') { return ''; } if ($needle === '') { return $haystack; } if (self::str_istarts_with($haystack, $needle)) { $haystack = (string) \mb_substr($haystack, (int) self::strlen($needle)); } return $haystack; } /** * Get part of a string process in bytes. * * @param string $strThe string being checked.
* @param int $offsetThe first position used in str.
* @param int|null $length [optional]The maximum length of the returned string.
* * @psalm-pure * * @return false|string *The portion of str specified by the offset and * length parameters.
If str is shorter than offset * characters long, FALSE will be returned.
*/ public static function substr_in_byte(string $str, int $offset = 0, int $length = null) { // empty string if ($str === '' || $length === 0) { return ''; } // whole string if (!$offset && $length === null) { return $str; } if (self::$SUPPORT['mbstring_func_overload'] === true) { // "mb_" is available if overload is used, so use it ... return \mb_substr($str, $offset, $length, 'CP850'); // 8-BIT } return \substr($str, $offset, $length ?? 2147483647); } /** * Removes a suffix ($needle) from the end of the string ($haystack), case-insensitive. * * EXAMPLE:
* UTF8::substr_iright('BeginMiddleΚόσμε', 'Κόσμε'); // 'BeginMiddle'
* UTF8::substr_iright('BeginMiddleΚόσμε', 'κόσμε'); // 'BeginMiddle'
*
*
* @param string $haystack The string to search in.
* @param string $needleThe substring to search for.
* * @psalm-pure * * @return string *Return the sub-string.
*/
public static function substr_iright(string $haystack, string $needle): string
{
if ($haystack === '') {
return '';
}
if ($needle === '') {
return $haystack;
}
if (self::str_iends_with($haystack, $needle)) {
$haystack = (string) \mb_substr($haystack, 0, (int) self::strlen($haystack) - (int) self::strlen($needle));
}
return $haystack;
}
/**
* Removes a prefix ($needle) from the beginning of the string ($haystack).
*
* EXAMPLE:
* UTF8::substr_left('ΚόσμεMiddleEnd', 'Κόσμε'); // 'MiddleEnd'
* UTF8::substr_left('ΚόσμεMiddleEnd', 'κόσμε'); // 'ΚόσμεMiddleEnd'
*
*
* @param string $haystack
The string to search in.
* @param string $needleThe substring to search for.
* * @psalm-pure * * @return string *Return the sub-string.
*/ public static function substr_left(string $haystack, string $needle): string { if ($haystack === '') { return ''; } if ($needle === '') { return $haystack; } if (self::str_starts_with($haystack, $needle)) { $haystack = (string) \mb_substr($haystack, (int) self::strlen($needle)); } return $haystack; } /** * Replace text within a portion of a string. * * EXAMPLE:UTF8::substr_replace(array('Iñtërnâtiônàlizætiøn', 'foo'), 'æ', 1); // array('Iæñtërnâtiônàlizætiøn', 'fæoo')
*
* source: https://gist.github.com/stemar/8287074
*
* @param string|string[] $str The input string or an array of stings.
* @param string|string[] $replacementThe replacement string or an array of stings.
* @param int|int[] $offset
* If start is positive, the replacing will begin at the start'th offset
* into string.
*
* If start is negative, the replacing will begin at the start'th character
* from the end of string.
*
If given and is positive, it represents the length of the * portion of string which is to be replaced. If it is negative, it * represents the number of characters from the end of string at which to * stop replacing. If it is not given, then it will default to strlen( * string ); i.e. end the replacing at the end of string. Of course, if * length is zero then this function will have the effect of inserting * replacement into string at the given start offset.
* @param string $encoding [optional]Set the charset for e.g. "mb_" function
* * @psalm-pure * * @return string|string[] *The result string is returned. If string is an array then array is returned.
* * @template TSubstrReplace string|string[] * @phpstan-param TSubstrReplace $str * @phpstan-return TSubstrReplace */ public static function substr_replace( $str, $replacement, $offset, $length = null, string $encoding = 'UTF-8' ) { if (\is_array($str)) { $num = \count($str); // the replacement if (\is_array($replacement)) { $replacement = \array_slice($replacement, 0, $num); } else { $replacement = \array_pad([$replacement], $num, $replacement); } // the offset if (\is_array($offset)) { $offset = \array_slice($offset, 0, $num); foreach ($offset as &$value_tmp) { $value_tmp = (int) $value_tmp === $value_tmp ? $value_tmp : 0; } unset($value_tmp); } else { $offset = \array_pad([$offset], $num, $offset); } // the length if ($length === null) { $length = \array_fill(0, $num, 0); } elseif (\is_array($length)) { $length = \array_slice($length, 0, $num); foreach ($length as &$value_tmp_V2) { $value_tmp_V2 = (int) $value_tmp_V2 === $value_tmp_V2 ? $value_tmp_V2 : $num; } unset($value_tmp_V2); } else { $length = \array_pad([$length], $num, $length); } // recursive call /** @phpstan-ignore-next-line - phpstan currently can't handle recursive calls */ return \array_map([self::class, 'substr_replace'], $str, $replacement, $offset, $length); } if (\is_array($replacement)) { if ($replacement !== []) { $replacement = $replacement[0]; } else { $replacement = ''; } } // init $str = (string) $str; $replacement = (string) $replacement; if (\is_array($length)) { throw new \InvalidArgumentException('Parameter "$length" can only be an array, if "$str" is also an array.'); } if (\is_array($offset)) { throw new \InvalidArgumentException('Parameter "$offset" can only be an array, if "$str" is also an array.'); } if ($str === '') { return $replacement; } if (self::$SUPPORT['mbstring'] === true) { $string_length = (int) self::strlen($str, $encoding); if ($offset < 0) { $offset = (int) \max(0, $string_length + $offset); } elseif ($offset > $string_length) { $offset = $string_length; } if ($length !== null && $length < 0) { $length = (int) \max(0, $string_length - $offset + $length); } elseif ($length === null || $length > $string_length) { $length = $string_length; } if (($offset + $length) > $string_length) { $length = $string_length - $offset; } return ((string) \mb_substr($str, 0, $offset, $encoding)) . $replacement . ((string) \mb_substr($str, $offset + $length, $string_length - $offset - $length, $encoding)); } // // fallback for ascii only // if (ASCII::is_ascii($str)) { return ($length === null) ? \substr_replace($str, $replacement, $offset) : \substr_replace($str, $replacement, $offset, $length); } // // fallback via vanilla php // \preg_match_all('/./us', $str, $str_matches); \preg_match_all('/./us', $replacement, $replacement_matches); if ($length === null) { $length_tmp = self::strlen($str, $encoding); if ($length_tmp === false) { // e.g.: non mbstring support + invalid chars return ''; } $length = $length_tmp; } \array_splice($str_matches[0], $offset, $length, $replacement_matches[0]); return \implode('', $str_matches[0]); } /** * Removes a suffix ($needle) from the end of the string ($haystack). * * EXAMPLE:
* UTF8::substr_right('BeginMiddleΚόσμε', 'Κόσμε'); // 'BeginMiddle'
* UTF8::substr_right('BeginMiddleΚόσμε', 'κόσμε'); // 'BeginMiddleΚόσμε'
*
*
* @param string $haystack The string to search in.
* @param string $needleThe substring to search for.
* @param string $encoding [optional]Set the charset for e.g. "mb_" function
* * @psalm-pure * * @return string *Return the sub-string.
*/ public static function substr_right( string $haystack, string $needle, string $encoding = 'UTF-8' ): string { if ($haystack === '') { return ''; } if ($needle === '') { return $haystack; } if ( $encoding === 'UTF-8' && \substr($haystack, -\strlen($needle)) === $needle ) { return (string) \mb_substr($haystack, 0, (int) \mb_strlen($haystack) - (int) \mb_strlen($needle)); } if (\substr($haystack, -\strlen($needle)) === $needle) { return (string) self::substr( $haystack, 0, (int) self::strlen($haystack, $encoding) - (int) self::strlen($needle, $encoding), $encoding ); } return $haystack; } /** * Returns a case swapped version of the string. * * EXAMPLE:UTF8::swapCase('déJÀ σσς iıII'); // 'DÉjà ΣΣΣ IIii'
*
* @param string $str The input string.
* @param string $encoding [optional]Set the charset for e.g. "mb_" function
* @param bool $clean_utf8 [optional]Remove non UTF-8 chars from the string.
* * @psalm-pure * * @return string *Each character's case swapped.
*/ public static function swapCase(string $str, string $encoding = 'UTF-8', bool $clean_utf8 = false): string { if ($str === '') { return ''; } if ($clean_utf8) { // "mb_strpos()" and "iconv_strpos()" returns wrong position, // if invalid characters are found in $haystack before $needle $str = self::clean($str); } if ($encoding === 'UTF-8') { return (string) (\mb_strtolower($str) ^ \mb_strtoupper($str) ^ $str); } return (string) (self::strtolower($str, $encoding) ^ self::strtoupper($str, $encoding) ^ $str); } /** * Checks whether symfony-polyfills are used. * * @psalm-pure * * @return bool *true if in use, false otherwise
* * @internalPlease do not use it anymore, we will make is private in next major version.
*/ public static function symfony_polyfill_used(): bool { // init $return = false; $return_tmp = \extension_loaded('mbstring'); if (!$return_tmp && \function_exists('mb_strlen')) { $return = true; } $return_tmp = \extension_loaded('iconv'); if (!$return_tmp && \function_exists('iconv')) { $return = true; } return $return; } /** * @param string $str * @param int $tab_length * * @psalm-pure * * @return string */ public static function tabs_to_spaces(string $str, int $tab_length = 4): string { if ($tab_length === 4) { $spaces = ' '; } elseif ($tab_length === 2) { $spaces = ' '; } else { $spaces = \str_repeat(' ', $tab_length); } return \str_replace("\t", $spaces, $str); } /** * Converts the first character of each word in the string to uppercase * and all other chars to lowercase. * * @param string $strThe input string.
* @param string $encoding [optional]Set the charset for e.g. "mb_" function
* @param bool $clean_utf8 [optional]Remove non UTF-8 chars from the string.
* @param string|null $lang [optional]Set the language for special cases: az, el, lt, * tr
* @param bool $try_to_keep_the_string_length [optional]true === try to keep the string length: e.g. ẞ * -> ß
* * @psalm-pure * * @return string *A string with all characters of $str being title-cased.
*/ public static function titlecase( string $str, string $encoding = 'UTF-8', bool $clean_utf8 = false, string $lang = null, bool $try_to_keep_the_string_length = false ): string { if ($clean_utf8) { // "mb_strpos()" and "iconv_strpos()" returns wrong position, // if invalid characters are found in $haystack before $needle $str = self::clean($str); } if ( $lang === null && !$try_to_keep_the_string_length ) { if ($encoding === 'UTF-8') { return \mb_convert_case($str, \MB_CASE_TITLE); } $encoding = self::normalize_encoding($encoding, 'UTF-8'); return \mb_convert_case($str, \MB_CASE_TITLE, $encoding); } return self::str_titleize( $str, null, $encoding, false, $lang, $try_to_keep_the_string_length, false ); } /** * Convert a string into ASCII. * * EXAMPLE:UTF8::to_ascii('déjà σσς iıii'); // 'deja sss iiii'
*
* @param string $str The input string.
* @param string $unknown [optional]Character use if character unknown. (default is ?)
* @param bool $strict [optional]Use "transliterator_transliterate()" from PHP-Intl | WARNING: bad * performance
* * @psalm-pure * * @return string */ public static function to_ascii( string $str, string $unknown = '?', bool $strict = false ): string { return ASCII::to_transliterate($str, $unknown, $strict); } /** * @param bool|float|int|string $str * * @psalm-pure * * @return bool */ public static function to_boolean($str): bool { // init $str = (string) $str; if ($str === '') { return false; } // Info: http://php.net/manual/en/filter.filters.validate.php $map = [ 'true' => true, '1' => true, 'on' => true, 'yes' => true, 'false' => false, '0' => false, 'off' => false, 'no' => false, ]; if (isset($map[$str])) { return $map[$str]; } $key = \strtolower($str); if (isset($map[$key])) { return $map[$key]; } if (\is_numeric($str)) { return ((float) $str) > 0; } return (bool) \trim($str); } /** * Convert given string to safe filename (and keep string case). * * @param string $str * @param bool $use_transliterate No transliteration, conversion etc. is done by default - unsafe characters are * simply replaced with hyphen. * @param string $fallback_char * * @psalm-pure * * @return string */ public static function to_filename( string $str, bool $use_transliterate = false, string $fallback_char = '-' ): string { return ASCII::to_filename( $str, $use_transliterate, $fallback_char ); } /** * Convert a string into "ISO-8859"-encoding (Latin-1). * * EXAMPLE:UTF8::to_utf8(UTF8::to_iso8859(' -ABC-中文空白- ')); // ' -ABC-????- '
*
* @param string|string[] $str
*
* @psalm-pure
*
* @return string|string[]
*
* @template TToIso8859 as string|string[]
* @phpstan-param TToIso8859 $str
* @phpstan-return (TToIso8859 is string ? string : string[])
*/
public static function to_iso8859($str)
{
if (\is_array($str)) {
foreach ($str as &$v) {
$v = self::to_iso8859($v);
}
return $str;
}
/* @phpstan-ignore-next-line | FP? -> "Cannot cast TToIso8859 of arrayUTF8::to_utf8(["\u0063\u0061\u0074"]); // array('cat')
*
* @param string|string[] $str Any string or array of strings.
* @param bool $decode_html_entity_to_utf8Set to true, if you need to decode html-entities.
* * @psalm-pure * * @return string|string[] *The UTF-8 encoded string
* * @template TToUtf8 as string|string[] * @phpstan-param TToUtf8 $str * @phpstan-return (TToUtf8 is string ? string : string[]) */ public static function to_utf8($str, bool $decode_html_entity_to_utf8 = false) { if (\is_array($str)) { foreach ($str as &$v) { $v = self::to_utf8_string($v, $decode_html_entity_to_utf8); } /** @phpstan-var TToUtf8 $str */ return $str; } \assert(\is_string($str)); $str = self::to_utf8_string($str, $decode_html_entity_to_utf8); /** @phpstan-var TToUtf8 $str */ return $str; } /** * This function leaves UTF-8 characters alone, while converting almost all non-UTF8 to UTF8. * *UTF8::to_utf8_string("\u0063\u0061\u0074"); // 'cat'
*
* @param string $str Any string.
* @param bool $decode_html_entity_to_utf8Set to true, if you need to decode html-entities.
* * @psalm-pure * * @return string *The UTF-8 encoded string
* * @template T as string * @phpstan-param T $str * @phpstan-return (T is non-empty-string ? non-empty-string : string) */ public static function to_utf8_string(string $str, bool $decode_html_entity_to_utf8 = false): string { if ($str === '') { return $str; } $max = \strlen($str); $buf = ''; for ($i = 0; $i < $max; ++$i) { $c1 = $str[$i]; if ($c1 >= "\xC0") { // should be converted to UTF8, if it's not UTF8 already if ($c1 <= "\xDF") { // looks like 2 bytes UTF8 $c2 = $i + 1 >= $max ? "\x00" : $str[$i + 1]; if ($c2 >= "\x80" && $c2 <= "\xBF") { // yeah, almost sure it's UTF8 already $buf .= $c1 . $c2; ++$i; } else { // not valid UTF8 - convert it $buf .= self::to_utf8_convert_helper($c1); } } elseif ($c1 >= "\xE0" && $c1 <= "\xEF") { // looks like 3 bytes UTF8 $c2 = $i + 1 >= $max ? "\x00" : $str[$i + 1]; $c3 = $i + 2 >= $max ? "\x00" : $str[$i + 2]; if ($c2 >= "\x80" && $c2 <= "\xBF" && $c3 >= "\x80" && $c3 <= "\xBF") { // yeah, almost sure it's UTF8 already $buf .= $c1 . $c2 . $c3; $i += 2; } else { // not valid UTF8 - convert it $buf .= self::to_utf8_convert_helper($c1); } } elseif ($c1 >= "\xF0" && $c1 <= "\xF7") { // looks like 4 bytes UTF8 $c2 = $i + 1 >= $max ? "\x00" : $str[$i + 1]; $c3 = $i + 2 >= $max ? "\x00" : $str[$i + 2]; $c4 = $i + 3 >= $max ? "\x00" : $str[$i + 3]; if ($c2 >= "\x80" && $c2 <= "\xBF" && $c3 >= "\x80" && $c3 <= "\xBF" && $c4 >= "\x80" && $c4 <= "\xBF") { // yeah, almost sure it's UTF8 already $buf .= $c1 . $c2 . $c3 . $c4; $i += 3; } else { // not valid UTF8 - convert it $buf .= self::to_utf8_convert_helper($c1); } } else { // doesn't look like UTF8, but should be converted $buf .= self::to_utf8_convert_helper($c1); } } elseif (($c1 & "\xC0") === "\x80") { // needs conversion $buf .= self::to_utf8_convert_helper($c1); } else { // it doesn't need conversion $buf .= $c1; } } // decode unicode escape sequences + unicode surrogate pairs $buf = \preg_replace_callback( '/\\\\u([dD][89abAB][0-9a-fA-F]{2})\\\\u([dD][cdefCDEF][\da-fA-F]{2})|\\\\u([0-9a-fA-F]{4})/', /** * @param array $matches * * @psalm-pure * * @return string */ static function (array $matches): string { if (isset($matches[3])) { $cp = (int) \hexdec($matches[3]); } else { // http://unicode.org/faq/utf_bom.html#utf16-4 $cp = ((int) \hexdec($matches[1]) << 10) + (int) \hexdec($matches[2]) + 0x10000 - (0xD800 << 10) - 0xDC00; } // https://github.com/php/php-src/blob/php-7.3.2/ext/standard/html.c#L471 // // php_utf32_utf8(unsigned char *buf, unsigned k) if ($cp < 0x80) { return (string) self::chr($cp); } if ($cp < 0xA0) { /** @noinspection UnnecessaryCastingInspection */ return (string) self::chr(0xC0 | $cp >> 6) . (string) self::chr(0x80 | $cp & 0x3F); } return self::decimal_to_chr($cp); }, $buf ); if ($buf === null) { return ''; } // decode UTF-8 codepoints if ($decode_html_entity_to_utf8) { $buf = self::html_entity_decode($buf); } return $buf; } /** * Returns the given string as an integer, or null if the string isn't numeric. * * @param string $str * * @psalm-pure * * @return int|null *null if the string isn't numeric
*/ public static function to_int(string $str) { if (\is_numeric($str)) { return (int) $str; } return null; } /** * Returns the given input as string, or null if the input isn't int|float|string * and do not implement the "__toString()" method. * * @param float|int|object|string|null $input * * @psalm-pure * * @return string|null *null if the input isn't int|float|string and has no "__toString()" method
*/ public static function to_string($input) { if ($input === null) { return null; } $input_type = \gettype($input); if ( $input_type === 'string' || $input_type === 'integer' || $input_type === 'float' || $input_type === 'double' ) { return (string) $input; } /** @phpstan-ignore-next-line - "gettype": FP? */ if ($input_type === 'object' && \method_exists($input, '__toString')) { return (string) $input; } return null; } /** * Strip whitespace or other characters from the beginning and end of a UTF-8 string. * * INFO: This is slower then "trim()" * * We can only use the original-function, if we use <= 7-Bit in the string / chars * but the check for ASCII (7-Bit) cost more time, then we can safe here. * * EXAMPLE:UTF8::trim(' -ABC-中文空白- '); // '-ABC-中文空白-'
*
* @param string $str The string to be trimmed
* @param string|null $chars [optional]Optional characters to be stripped
* * @psalm-pure * * @return string *The trimmed string.
*/ public static function trim(string $str = '', string $chars = null): string { if ($str === '') { return ''; } if (self::$SUPPORT['mbstring'] === true) { if ($chars !== null) { /** @noinspection PregQuoteUsageInspection */ $chars = \preg_quote($chars); $pattern = "^[{$chars}]+|[{$chars}]+\$"; } else { $pattern = '^[\\s]+|[\\s]+$'; } return (string) \mb_ereg_replace($pattern, '', $str); } if ($chars !== null) { $chars = \preg_quote($chars, '/'); $pattern = "^[{$chars}]+|[{$chars}]+\$"; } else { $pattern = '^[\\s]+|[\\s]+$'; } return self::regex_replace($str, $pattern, ''); } /** * Makes string's first char uppercase. * * EXAMPLE:UTF8::ucfirst('ñtërnâtiônàlizætiøn foo'); // 'Ñtërnâtiônàlizætiøn foo'
*
* @param string $str The input string.
* @param string $encoding [optional]Set the charset for e.g. "mb_" function
* @param bool $clean_utf8 [optional]Remove non UTF-8 chars from the string.
* @param string|null $lang [optional]Set the language for special cases: az, el, lt, * tr
* @param bool $try_to_keep_the_string_length [optional]true === try to keep the string length: e.g. ẞ * -> ß
* * @psalm-pure * * @return string *The resulting string with with char uppercase.
*/ public static function ucfirst( string $str, string $encoding = 'UTF-8', bool $clean_utf8 = false, string $lang = null, bool $try_to_keep_the_string_length = false ): string { if ($str === '') { return ''; } if ($clean_utf8) { // "mb_strpos()" and "iconv_strpos()" returns wrong position, // if invalid characters are found in $haystack before $needle $str = self::clean($str); } $use_mb_functions = $lang === null && !$try_to_keep_the_string_length; if ($encoding === 'UTF-8') { $str_part_two = (string) \mb_substr($str, 1); if ($use_mb_functions) { $str_part_one = \mb_strtoupper( (string) \mb_substr($str, 0, 1) ); } else { $str_part_one = self::strtoupper( (string) \mb_substr($str, 0, 1), $encoding, false, $lang, $try_to_keep_the_string_length ); } } else { $encoding = self::normalize_encoding($encoding, 'UTF-8'); $str_part_two = (string) self::substr($str, 1, null, $encoding); if ($use_mb_functions) { $str_part_one = \mb_strtoupper( (string) \mb_substr($str, 0, 1, $encoding), $encoding ); } else { $str_part_one = self::strtoupper( (string) self::substr($str, 0, 1, $encoding), $encoding, false, $lang, $try_to_keep_the_string_length ); } } return $str_part_one . $str_part_two; } /** * Uppercase for all words in the string. * * EXAMPLE:UTF8::ucwords('iñt ërn âTi ônà liz æti øn'); // 'Iñt Ërn ÂTi Ônà Liz Æti Øn'
*
* @param string $str The input string.
* @param string[] $exceptions [optional]Exclusion for some words.
* @param string $char_list [optional]Additional chars that contains to words and do not start a new * word.
* @param string $encoding [optional]Set the charset.
* @param bool $clean_utf8 [optional]Remove non UTF-8 chars from the string.
* * @psalm-pure * * @return string */ public static function ucwords( string $str, array $exceptions = [], string $char_list = '', string $encoding = 'UTF-8', bool $clean_utf8 = false ): string { if (!$str) { return ''; } // INFO: mb_convert_case($str, MB_CASE_TITLE); // -> MB_CASE_TITLE didn't only uppercase the first letter, it also lowercase all other letters if ($clean_utf8) { // "mb_strpos()" and "iconv_strpos()" returns wrong position, // if invalid characters are found in $haystack before $needle $str = self::clean($str); } $use_php_default_functions = !(bool) ($char_list . \implode('', $exceptions)); if ( $use_php_default_functions && ASCII::is_ascii($str) ) { return \ucwords($str); } $words = self::str_to_words($str, $char_list); $use_exceptions = $exceptions !== []; $words_str = ''; foreach ($words as &$word) { if (!$word) { continue; } if ( !$use_exceptions || !\in_array($word, $exceptions, true) ) { $words_str .= self::ucfirst($word, $encoding); } else { $words_str .= $word; } } return $words_str; } /** * Multi decode HTML entity + fix urlencoded-win1252-chars. * * EXAMPLE:UTF8::urldecode('tes%20öäü%20\u00edtest+test'); // 'tes öäü ítest test'
*
* e.g:
* 'test+test' => 'test test'
* 'Düsseldorf' => 'Düsseldorf'
* 'D%FCsseldorf' => 'Düsseldorf'
* 'Düsseldorf' => 'Düsseldorf'
* 'D%26%23xFC%3Bsseldorf' => 'Düsseldorf'
* 'Düsseldorf' => 'Düsseldorf'
* 'D%C3%BCsseldorf' => 'Düsseldorf'
* 'D%C3%83%C2%BCsseldorf' => 'Düsseldorf'
* 'D%25C3%2583%25C2%25BCsseldorf' => 'Düsseldorf'
*
* @param string $str The input string.
* @param bool $multi_decodeDecode as often as possible.
* * @psalm-pure * * @return string * * @template T as string * @phpstan-param T $str * @phpstan-return (T is non-empty-string ? non-empty-string : string) */ public static function urldecode(string $str, bool $multi_decode = true): string { if ($str === '') { return ''; } $str = self::urldecode_unicode_helper($str); if ($multi_decode) { do { $str_compare = $str; /** * @psalm-suppress PossiblyInvalidArgument */ $str = \urldecode( self::html_entity_decode( self::to_utf8($str), \ENT_QUOTES | \ENT_HTML5 ) ); } while ($str_compare !== $str); } else { /** * @psalm-suppress PossiblyInvalidArgument */ $str = \urldecode( self::html_entity_decode( self::to_utf8($str), \ENT_QUOTES | \ENT_HTML5 ) ); } return self::fix_simple_utf8($str); } /** * Decodes a UTF-8 string to ISO-8859-1. * * EXAMPLE:UTF8::encode('UTF-8', UTF8::utf8_decode('-ABC-中文空白-')); // '-ABC-????-'
*
* @param string $str The input string.
* @param bool $keep_utf8_chars * * @psalm-pure * * @return string */ public static function utf8_decode(string $str, bool $keep_utf8_chars = false): string { if ($str === '') { return ''; } // save for later comparision $str_backup = $str; $len = \strlen($str); if (self::$ORD === null) { self::$ORD = self::getData('ord'); } if (self::$CHR === null) { self::$CHR = self::getData('chr'); } $no_char_found = '?'; for ($i = 0, $j = 0; $i < $len; ++$i, ++$j) { switch ($str[$i] & "\xF0") { case "\xC0": case "\xD0": $c = (self::$ORD[$str[$i] & "\x1F"] << 6) | self::$ORD[$str[++$i] & "\x3F"]; $str[$j] = $c < 256 ? self::$CHR[$c] : $no_char_found; break; case "\xF0": ++$i; // no break case "\xE0": $str[$j] = $no_char_found; $i += 2; break; default: $str[$j] = $str[$i]; } } /** @var false|string $return - needed for PhpStan (stubs error) */ $return = \substr($str, 0, $j); if ($return === false) { $return = ''; } if ( $keep_utf8_chars && (int) self::strlen($return) >= (int) self::strlen($str_backup) ) { return $str_backup; } return $return; } /** * Encodes an ISO-8859-1 string to UTF-8. * * EXAMPLE:UTF8::utf8_decode(UTF8::utf8_encode('-ABC-中文空白-')); // '-ABC-中文空白-'
*
* @param string $str The input string.
* * @psalm-pure * * @return string */ public static function utf8_encode(string $str): string { if ($str === '') { return ''; } /** @noinspection PhpUsageOfSilenceOperatorInspection | TODO for PHP > 8.2: find a replacement for this */ /** @var false|string $str - the polyfill maybe return false */ $str = @\utf8_encode($str); if ($str === false) { return ''; } return $str; } /** * Returns an array with all utf8 whitespace characters. * * @see http://www.bogofilter.org/pipermail/bogofilter/2003-March/001889.html * * @psalm-pure * * @return string[] * An array with all known whitespace characters as values and the type of whitespace as keys * as defined in above URL */ public static function whitespace_table(): array { return self::$WHITESPACE_TABLE; } /** * Limit the number of words in a string. * * EXAMPLE:UTF8::words_limit('fòô bàř fòô', 2, ''); // 'fòô bàř'
*
* @param string $str The input string.
* @param int<1, max> $limitThe limit of words as integer.
* @param string $str_add_onReplacement for the striped string.
* * @psalm-pure * * @return string */ public static function words_limit( string $str, int $limit = 100, string $str_add_on = '…' ): string { if ( $str === '' || /* @phpstan-ignore-next-line | we do not trust the phpdoc check */ $limit <= 0 ) { return ''; } \preg_match('/^\\s*+(?:[^\\s]++\\s*+){1,' . $limit . '}/u', $str, $matches); if ( !isset($matches[0]) || \mb_strlen($str) === (int) \mb_strlen($matches[0]) ) { return $str; } return \rtrim($matches[0]) . $str_add_on; } /** * Wraps a string to a given number of characters * * EXAMPLE:UTF8::wordwrap('Iñtërnâtiônàlizætiøn', 2, '
', true)); // 'Iñ
të
rn
ât
iô
nà
li
zæ
ti
øn'
*
* @see http://php.net/manual/en/function.wordwrap.php
*
* @param string $str The input string.
* @param int<1, max> $width [optional]The column width.
* @param string $break [optional]The line is broken using the optional break parameter.
* @param bool $cut [optional]* If the cut is set to true, the string is * always wrapped at or before the specified width. So if you have * a word that is larger than the given width, it is broken apart. *
* * @psalm-pure * * @return string *The given string wrapped at the specified column.
*/ public static function wordwrap( string $str, int $width = 75, string $break = "\n", bool $cut = false ): string { if ($str === '' || $break === '') { return ''; } $str_split = \explode($break, $str); /** @var string[] $charsArray */ $charsArray = []; $word_split = ''; foreach ($str_split as $i => $i_value) { if ($i) { $charsArray[] = $break; $word_split .= '#'; } foreach (self::str_split($i_value) as $c) { $charsArray[] = $c; if ($c === ' ') { $word_split .= ' '; } else { $word_split .= '?'; } } } $str_return = ''; $j = 0; $b = -1; $i = -1; $word_split = \wordwrap($word_split, $width, '#', $cut); $max = \mb_strlen($word_split); /** @noinspection PhpAssignmentInConditionInspection - is ok here */ while (($b = \mb_strpos($word_split, '#', $b + 1)) !== false) { for (++$i; $i < $b; ++$i) { if (isset($charsArray[$j])) { $str_return .= $charsArray[$j]; unset($charsArray[$j]); } ++$j; // prevent endless loop, e.g. if there is a error in the "mb_*" polyfill if ($i > $max) { break 2; } } if ( $break === $charsArray[$j] || $charsArray[$j] === ' ' ) { unset($charsArray[$j++]); } $str_return .= $break; // prevent endless loop, e.g. if there is a error in the "mb_*" polyfill if ($b > $max) { break; } } return $str_return . \implode('', $charsArray); } /** * Line-Wrap the string after $limit, but split the string by "$delimiter" before ... * ... so that we wrap the per line. * * @param string $strThe input string.
* @param int<1, max> $width [optional]The column width.
* @param string $break [optional]The line is broken using the optional break parameter.
* @param bool $cut [optional]* If the cut is set to true, the string is * always wrapped at or before the specified width. So if you have * a word that is larger than the given width, it is broken apart. *
* @param bool $add_final_break [optional]* If this flag is true, then the method will add a $break at the end * of the result string. *
* @param non-empty-string|null $delimiter [optional]* You can change the default behavior, where we split the string by newline. *
* * @psalm-pure * * @return string */ public static function wordwrap_per_line( string $str, int $width = 75, string $break = "\n", bool $cut = false, bool $add_final_break = true, string $delimiter = null ): string { if ($delimiter === null) { $strings = \preg_split('/\\r\\n|\\r|\\n/', $str); } else { $strings = \explode($delimiter, $str); } $string_helper_array = []; if ($strings !== false) { foreach ($strings as $value) { $string_helper_array[] = self::wordwrap($value, $width, $break, $cut); } } if ($add_final_break) { $final_break = $break; } else { $final_break = ''; } return \implode($delimiter ?? "\n", $string_helper_array) . $final_break; } /** * Returns an array of Unicode White Space characters. * * @psalm-pure * * @return string[] *An array with numeric code point as key and White Space Character as value.
*/ public static function ws(): array { return self::$WHITESPACE; } /** * Checks whether the passed string contains only byte sequences that are valid UTF-8 characters. * * EXAMPLE:
* UTF8::is_utf8_string('Iñtërnâtiônàlizætiøn']); // true
* //
* UTF8::is_utf8_string("Iñtërnâtiônàlizætiøn\xA0\xA1"); // false
*
*
* @see http://hsivonen.iki.fi/php-utf8/
*
* @param string $str The string to be checked.
* @param bool $strictCheck also if the string is not UTF-16 or UTF-32.
* * @psalm-pure * * @return bool */ private static function is_utf8_string(string $str, bool $strict = false) { if ($str === '') { return true; } if ($strict) { $is_binary = self::is_binary($str, true); if ($is_binary && self::is_utf16($str, false) !== false) { return false; } if ($is_binary && self::is_utf32($str, false) !== false) { return false; } } if (self::$SUPPORT['pcre_utf8']) { // If even just the first character can be matched, when the /u // modifier is used, then it's valid UTF-8. If the UTF-8 is somehow // invalid, nothing at all will match, even if the string contains // some valid sequences return \preg_match('/^./us', $str) === 1; } $mState = 0; // cached expected number of octets after the current octet // until the beginning of the next UTF8 character sequence $mUcs4 = 0; // cached Unicode character $mBytes = 1; // cached expected number of octets in the current sequence if (self::$ORD === null) { self::$ORD = self::getData('ord'); } $len = \strlen($str); for ($i = 0; $i < $len; ++$i) { $in = self::$ORD[$str[$i]]; if ($mState === 0) { // When mState is zero we expect either a US-ASCII character or a // multi-octet sequence. if ((0x80 & $in) === 0) { // US-ASCII, pass straight through. $mBytes = 1; } elseif ((0xE0 & $in) === 0xC0) { // First octet of 2 octet sequence. $mUcs4 = $in; $mUcs4 = ($mUcs4 & 0x1F) << 6; $mState = 1; $mBytes = 2; } elseif ((0xF0 & $in) === 0xE0) { // First octet of 3 octet sequence. $mUcs4 = $in; $mUcs4 = ($mUcs4 & 0x0F) << 12; $mState = 2; $mBytes = 3; } elseif ((0xF8 & $in) === 0xF0) { // First octet of 4 octet sequence. $mUcs4 = $in; $mUcs4 = ($mUcs4 & 0x07) << 18; $mState = 3; $mBytes = 4; } elseif ((0xFC & $in) === 0xF8) { /* First octet of 5 octet sequence. * * This is illegal because the encoded codepoint must be either * (a) not the shortest form or * (b) outside the Unicode range of 0-0x10FFFF. * Rather than trying to resynchronize, we will carry on until the end * of the sequence and let the later error handling code catch it. */ $mUcs4 = $in; $mUcs4 = ($mUcs4 & 0x03) << 24; $mState = 4; $mBytes = 5; } elseif ((0xFE & $in) === 0xFC) { // First octet of 6 octet sequence, see comments for 5 octet sequence. $mUcs4 = $in; $mUcs4 = ($mUcs4 & 1) << 30; $mState = 5; $mBytes = 6; } else { // Current octet is neither in the US-ASCII range nor a legal first // octet of a multi-octet sequence. return false; } } elseif ((0xC0 & $in) === 0x80) { // When mState is non-zero, we expect a continuation of the multi-octet // sequence // Legal continuation. $shift = ($mState - 1) * 6; $tmp = $in; $tmp = ($tmp & 0x0000003F) << $shift; $mUcs4 |= $tmp; // Prefix: End of the multi-octet sequence. mUcs4 now contains the final // Unicode code point to be output. if (--$mState === 0) { // Check for illegal sequences and code points. // // From Unicode 3.1, non-shortest form is illegal if ( ($mBytes === 2 && $mUcs4 < 0x0080) || ($mBytes === 3 && $mUcs4 < 0x0800) || ($mBytes === 4 && $mUcs4 < 0x10000) || ($mBytes > 4) || // From Unicode 3.2, surrogate characters are illegal. (($mUcs4 & 0xFFFFF800) === 0xD800) || // Code points outside the Unicode range are illegal. ($mUcs4 > 0x10FFFF) ) { return false; } // initialize UTF8 cache $mState = 0; $mUcs4 = 0; $mBytes = 1; } } else { // ((0xC0 & (*in) != 0x80) && (mState != 0)) // Incomplete multi-octet sequence. return false; } } return $mState === 0; } /** * @param string $str * @param bool $use_lowercaseUse uppercase by default, otherwise use lowercase.
* @param bool $use_full_case_foldConvert not only common cases.
* * @psalm-pure * * @return string */ private static function fixStrCaseHelper( string $str, bool $use_lowercase = false, bool $use_full_case_fold = false ) { $upper = self::$COMMON_CASE_FOLD['upper']; $lower = self::$COMMON_CASE_FOLD['lower']; if ($use_lowercase) { $str = \str_replace( $upper, $lower, $str ); } else { $str = \str_replace( $lower, $upper, $str ); } if ($use_full_case_fold) { /** * @psalm-suppress ImpureStaticVariable * * @var arrayThe input string
* * @psalm-pure * * @return string|null */ private static function strtonatfold(string $str) { $str = \Normalizer::normalize($str, \Normalizer::NFD); if ($str === false) { return ''; } return \preg_replace( '/\p{Mn}+/u', '', $str ); } /** * @param int|string $input * * @psalm-pure * * @return string */ private static function to_utf8_convert_helper($input) { // init $buf = ''; if (self::$ORD === null) { self::$ORD = self::getData('ord'); } if (self::$CHR === null) { self::$CHR = self::getData('chr'); } if (self::$WIN1252_TO_UTF8 === null) { self::$WIN1252_TO_UTF8 = self::getData('win1252_to_utf8'); } $ordC1 = self::$ORD[$input]; if (isset(self::$WIN1252_TO_UTF8[$ordC1])) { // found in Windows-1252 special cases $buf .= self::$WIN1252_TO_UTF8[$ordC1]; } else { $cc1 = self::$CHR[$ordC1 / 64] | "\xC0"; $cc2 = ((string) $input & "\x3F") | "\x80"; $buf .= $cc1 . $cc2; } return $buf; } /** * @param string $str * * @psalm-pure * * @return string */ private static function urldecode_unicode_helper(string $str) { if (\strpos($str, '%u') === false) { return $str; } $pattern = '/%u([0-9a-fA-F]{3,4})/'; if (\preg_match($pattern, $str)) { $str = (string) \preg_replace($pattern, '\\1;', $str); } return $str; } }