UTF8::htmlentities('<白-öäü>'); // '<白-öäü>'
*
* @see http://php.net/manual/en/function.htmlentities.php
*
* @param string $str * The input string. *
* @param int $flags [optional]* A bitmask of one or more of the following flags, which specify how to handle * quotes, invalid code unit sequences and the used document type. The default is * ENT_COMPAT | ENT_HTML401. *
| Constant Name | *Description | *
| ENT_COMPAT | *Will convert double-quotes and leave single-quotes alone. | *
| ENT_QUOTES | *Will convert both double and single quotes. | *
| ENT_NOQUOTES | *Will leave both double and single quotes unconverted. | *
| ENT_IGNORE | ** Silently discard invalid code unit sequences instead of returning * an empty string. Using this flag is discouraged as it * may have security implications. * | *
| ENT_SUBSTITUTE | ** Replace invalid code unit sequences with a Unicode Replacement Character * U+FFFD (UTF-8) or &#FFFD; (otherwise) instead of returning an empty * string. * | *
| ENT_DISALLOWED | ** Replace invalid code points for the given document type with a * Unicode Replacement Character U+FFFD (UTF-8) or &#FFFD; * (otherwise) instead of leaving them as is. This may be useful, for * instance, to ensure the well-formedness of XML documents with * embedded external content. * | *
| ENT_HTML401 | ** Handle code as HTML 4.01. * | *
| ENT_XML1 | ** Handle code as XML 1. * | *
| ENT_XHTML | ** Handle code as XHTML. * | *
| ENT_HTML5 | ** Handle code as HTML 5. * | *
* Like htmlspecialchars, * htmlentities takes an optional third argument * encoding which defines encoding used in * conversion. * Although this argument is technically optional, you are highly * encouraged to specify the correct value for your code. *
* @param bool $double_encode [optional]* When double_encode is turned off PHP will not * encode existing html entities. The default is to convert everything. *
* * @psalm-pure * * @return string *
* The encoded string.
*
* If the input string contains an invalid code unit
* sequence within the given encoding an empty string
* will be returned, unless either the ENT_IGNORE or
* ENT_SUBSTITUTE flags are set.
*
UTF8::htmlspecialchars('<白-öäü>'); // '<白-öäü>'
*
* @see http://php.net/manual/en/function.htmlspecialchars.php
*
* @param string $str * The string being converted. *
* @param int $flags [optional]* A bitmask of one or more of the following flags, which specify how to handle * quotes, invalid code unit sequences and the used document type. The default is * ENT_COMPAT | ENT_HTML401. *
| Constant Name | *Description | *
| ENT_COMPAT | *Will convert double-quotes and leave single-quotes alone. | *
| ENT_QUOTES | *Will convert both double and single quotes. | *
| ENT_NOQUOTES | *Will leave both double and single quotes unconverted. | *
| ENT_IGNORE | ** Silently discard invalid code unit sequences instead of returning * an empty string. Using this flag is discouraged as it * may have security implications. * | *
| ENT_SUBSTITUTE | ** Replace invalid code unit sequences with a Unicode Replacement Character * U+FFFD (UTF-8) or &#FFFD; (otherwise) instead of returning an empty * string. * | *
| ENT_DISALLOWED | ** Replace invalid code points for the given document type with a * Unicode Replacement Character U+FFFD (UTF-8) or &#FFFD; * (otherwise) instead of leaving them as is. This may be useful, for * instance, to ensure the well-formedness of XML documents with * embedded external content. * | *
| ENT_HTML401 | ** Handle code as HTML 4.01. * | *
| ENT_XML1 | ** Handle code as XML 1. * | *
| ENT_XHTML | ** Handle code as XHTML. * | *
| ENT_HTML5 | ** Handle code as HTML 5. * | *
* Defines encoding used in conversion. *
** For the purposes of this function, the encodings * ISO-8859-1, ISO-8859-15, * UTF-8, cp866, * cp1251, cp1252, and * KOI8-R are effectively equivalent, provided the * string itself is valid for the encoding, as * the characters affected by htmlspecialchars occupy * the same positions in all of these encodings. *
* @param bool $double_encode [optional]* When double_encode is turned off PHP will not * encode existing html entities, the default is to convert everything. *
* * @psalm-pure * * @return string *The converted string.
** If the input string contains an invalid code unit * sequence within the given encoding an empty string * will be returned, unless either the ENT_IGNORE or * ENT_SUBSTITUTE flags are set.
* * @template T as string * @phpstan-param T $str * @phpstan-return (T is non-empty-string ? non-empty-string : string) */ public static function htmlspecialchars( string $str, int $flags = \ENT_COMPAT, string $encoding = 'UTF-8', bool $double_encode = true ): string { if ($encoding !== 'UTF-8' && $encoding !== 'CP850') { $encoding = self::normalize_encoding($encoding, 'UTF-8'); } return \htmlspecialchars( $str, $flags, $encoding, $double_encode ); } /** * Checks whether iconv is available on the server. * * @psalm-pure * * @return bool *true if available, false otherwise
* * @internalPlease do not use it anymore, we will make is private in next major version.
*/ public static function iconv_loaded(): bool { return \extension_loaded('iconv'); } /** * Converts Integer to hexadecimal U+xxxx code point representation. * * INFO: opposite to UTF8::hex_to_int() * * EXAMPLE:UTF8::int_to_hex(241); // 'U+00f1'
*
* @param int $int The integer to be converted to hexadecimal code point.
* @param string $prefix [optional] * * @psalm-pure * * @return string the code point, or empty string on failure */ public static function int_to_hex(int $int, string $prefix = 'U+'): string { $hex = \dechex($int); $hex = (\strlen($hex) < 4 ? \substr('0000' . $hex, -4) : $hex); return $prefix . $hex . ''; } /** * Checks whether intl-char is available on the server. * * @psalm-pure * * @return bool *true if available, false otherwise
* * @internalPlease do not use it anymore, we will make is private in next major version.
*/ public static function intlChar_loaded(): bool { return \class_exists('IntlChar'); } /** * Checks whether intl is available on the server. * * @psalm-pure * * @return bool *true if available, false otherwise
* * @internalPlease do not use it anymore, we will make is private in next major version.
*/ public static function intl_loaded(): bool { return \extension_loaded('intl'); } /** * Returns true if the string contains only alphabetic chars, false otherwise. * * @param string $strThe input string.
* * @psalm-pure * * @return bool *Whether or not $str contains only alphabetic chars.
*/ public static function is_alpha(string $str): bool { if (self::$SUPPORT['mbstring'] === true) { return \mb_ereg_match('^[[:alpha:]]*$', $str); } return self::str_matches_pattern($str, '^[[:alpha:]]*$'); } /** * Returns true if the string contains only alphabetic and numeric chars, false otherwise. * * @param string $strThe input string.
* * @psalm-pure * * @return bool *Whether or not $str contains only alphanumeric chars.
*/ public static function is_alphanumeric(string $str): bool { if (self::$SUPPORT['mbstring'] === true) { return \mb_ereg_match('^[[:alnum:]]*$', $str); } return self::str_matches_pattern($str, '^[[:alnum:]]*$'); } /** * Returns true if the string contains only punctuation chars, false otherwise. * * @param string $strThe input string.
* * @psalm-pure * * @return bool *Whether or not $str contains only punctuation chars.
*/ public static function is_punctuation(string $str): bool { return self::str_matches_pattern($str, '^[[:punct:]]*$'); } /** * Returns true if the string contains only printable (non-invisible) chars, false otherwise. * * @param string $strThe input string.
* @param bool $ignore_control_characters [optional]Ignore control characters like [LRM] or [LSEP].
* * @psalm-pure * * @return bool *Whether or not $str contains only printable (non-invisible) chars.
*/ public static function is_printable(string $str, bool $ignore_control_characters = false): bool { return self::remove_invisible_characters($str, false, '', $ignore_control_characters) === $str; } /** * Checks if a string is 7 bit ASCII. * * EXAMPLE:UTF8::is_ascii('白'); // false
*
* @param string $str The string to check.
* * @psalm-pure * * @return bool *
* true if it is ASCII
* false otherwise
*
UTF8::is_base64('4KSu4KWL4KSo4KS/4KSa'); // true
*
* @param string|null $str The input string.
* @param bool $empty_string_is_valid [optional]Is an empty string valid base64 or not?
* * @psalm-pure * * @return bool *Whether or not $str is base64 encoded.
*/ public static function is_base64($str, bool $empty_string_is_valid = false): bool { if ( !$empty_string_is_valid && $str === '' ) { return false; } if (!\is_string($str)) { return false; } $base64String = \base64_decode($str, true); return $base64String !== false && \base64_encode($base64String) === $str; } /** * Check if the input is binary... (is look like a hack). * * EXAMPLE:UTF8::is_binary(01); // true
*
* @param int|string $input
* @param bool $strict
*
* @psalm-pure
*
* @return bool
*/
public static function is_binary($input, bool $strict = false): bool
{
$input = (string) $input;
if ($input === '') {
return false;
}
if (\preg_match('~^[01]+$~', $input)) {
return true;
}
$ext = self::get_file_type($input);
if ($ext['type'] === 'binary') {
return true;
}
if (!$strict) {
$test_length = \strlen($input);
$test_null_counting = \substr_count($input, "\x0", 0, $test_length);
if (($test_null_counting / $test_length) > 0.25) {
return true;
}
}
if ($strict) {
if (self::$SUPPORT['finfo'] === false) {
throw new \RuntimeException('ext-fileinfo: is not installed');
}
/**
* @psalm-suppress ImpureMethodCall - it will return the same result for the same file ...
*/
$finfo_encoding = (new \finfo(\FILEINFO_MIME_ENCODING))->buffer($input);
if ($finfo_encoding && $finfo_encoding === 'binary') {
return true;
}
}
return false;
}
/**
* Check if the file is binary.
*
* EXAMPLE: UTF8::is_binary('./utf32.txt'); // true
*
* @param string $file
*
* @return bool
*/
public static function is_binary_file($file): bool
{
// init
$block = '';
$fp = \fopen($file, 'rb');
if (\is_resource($fp)) {
$block = \fread($fp, 512);
\fclose($fp);
}
if ($block === '' || $block === false) {
return false;
}
return self::is_binary($block, true);
}
/**
* Returns true if the string contains only whitespace chars, false otherwise.
*
* @param string $str The input string.
* * @psalm-pure * * @return bool *Whether or not $str contains only whitespace characters.
*/ public static function is_blank(string $str): bool { if (self::$SUPPORT['mbstring'] === true) { return \mb_ereg_match('^[[:space:]]*$', $str); } return self::str_matches_pattern($str, '^[[:space:]]*$'); } /** * Checks if the given string is equal to any "Byte Order Mark". * * WARNING: Use "UTF8::string_has_bom()" if you will check BOM in a string. * * EXAMPLE:UTF8::is_bom("\xef\xbb\xbf"); // true
*
* @param string $str The input string.
* * @psalm-pure * * @return bool *true if the $utf8_chr is Byte Order Mark, false otherwise.
*/ public static function is_bom($str): bool { /** @noinspection PhpUnusedLocalVariableInspection */ foreach (self::$BOM as $bom_string => &$bom_byte_length) { if ($str === $bom_string) { return true; } } return false; } /** * Determine whether the string is considered to be empty. * * A variable is considered empty if it does not exist or if its value equals FALSE. * empty() does not generate a warning if the variable does not exist. * * @param arrayWhether or not $str is empty().
*/ public static function is_empty($str): bool { return empty($str); } /** * Returns true if the string contains only hexadecimal chars, false otherwise. * * @param string $strThe input string.
* * @psalm-pure * * @return bool *Whether or not $str contains only hexadecimal chars.
*/ public static function is_hexadecimal(string $str): bool { if (self::$SUPPORT['mbstring'] === true) { return \mb_ereg_match('^[[:xdigit:]]*$', $str); } return self::str_matches_pattern($str, '^[[:xdigit:]]*$'); } /** * Check if the string contains any HTML tags. * * EXAMPLE:UTF8::is_html('lall'); // true
*
* @param string $str The input string.
* * @psalm-pure * * @return bool *Whether or not $str contains html elements.
*/ public static function is_html(string $str): bool { if ($str === '') { return false; } // init $matches = []; $str = self::emoji_encode($str); // hack for emoji support :/ \preg_match("/<\\/?\\w+(?:(?:\\s+\\w+(?:\\s*=\\s*(?:\".*?\"|'.*?'|[^'\">\\s]+))?)*\\s*|\\s*)\\/?>/u", $str, $matches); return $matches !== []; } /** * Check if $url is an correct url. * * @param string $url * @param bool $disallow_localhost * * @psalm-pure * * @return bool */ public static function is_url(string $url, bool $disallow_localhost = false): bool { if ($url === '') { return false; } // WARNING: keep this as hack protection if (!self::str_istarts_with_any($url, ['http://', 'https://'])) { return false; } // e.g. -> the server itself connect to "https://foo.localhost/phpmyadmin/... if ($disallow_localhost) { if (self::str_istarts_with_any( $url, [ 'http://localhost', 'https://localhost', 'http://127.0.0.1', 'https://127.0.0.1', 'http://::1', 'https://::1', ] )) { return false; } $regex = '/^(?:http(?:s)?:\/\/).*?(?:\.localhost)/iu'; if (\preg_match($regex, $url)) { return false; } } // INFO: this is needed for e.g. "http://müller.de/" (internationalized domain names) and non ASCII-parameters $regex = '/^(?:http(?:s)?:\\/\\/)(?:[\p{L}0-9][\p{L}0-9_-]*(?:\\.[\p{L}0-9][\p{L}0-9_-]*))(?:\\d+)?(?:\\/\\.*)?/iu'; if (\preg_match($regex, $url)) { return true; } return \filter_var($url, \FILTER_VALIDATE_URL) !== false; } /** * Try to check if "$str" is a JSON-string. * * EXAMPLE:UTF8::is_json('{"array":[1,"¥","ä"]}'); // true
*
* @param string $str The input string.
* @param bool $only_array_or_object_results_are_valid [optional]Only array and objects are valid json * results.
* * @return bool *Whether or not the $str is in JSON format.
*/ public static function is_json(string $str, bool $only_array_or_object_results_are_valid = true): bool { if ($str === '') { return false; } if (self::$SUPPORT['json'] === false) { throw new \RuntimeException('ext-json: is not installed'); } $jsonOrNull = self::json_decode($str); if ($jsonOrNull === null && \strtoupper($str) !== 'NULL') { return false; } if ( $only_array_or_object_results_are_valid && !\is_object($jsonOrNull) && !\is_array($jsonOrNull) ) { return false; } return \json_last_error() === \JSON_ERROR_NONE; } /** * @param string $strThe input string.
* * @psalm-pure * * @return bool *Whether or not $str contains only lowercase chars.
*/ public static function is_lowercase(string $str): bool { if (self::$SUPPORT['mbstring'] === true) { return \mb_ereg_match('^[[:lower:]]*$', $str); } return self::str_matches_pattern($str, '^[[:lower:]]*$'); } /** * Returns true if the string is serialized, false otherwise. * * @param string $strThe input string.
* * @psalm-pure * * @return bool *Whether or not $str is serialized.
*/ public static function is_serialized(string $str): bool { if ($str === '') { return false; } /** @noinspection PhpUsageOfSilenceOperatorInspection */ /** @noinspection UnserializeExploitsInspection */ return $str === 'b:0;' || @\unserialize($str, []) !== false; } /** * Returns true if the string contains only lower case chars, false * otherwise. * * @param string $strThe input string.
* * @psalm-pure * * @return bool *Whether or not $str contains only lower case characters.
*/ public static function is_uppercase(string $str): bool { if (self::$SUPPORT['mbstring'] === true) { return \mb_ereg_match('^[[:upper:]]*$', $str); } return self::str_matches_pattern($str, '^[[:upper:]]*$'); } /** * Check if the string is UTF-16. * * EXAMPLE:
* UTF8::is_utf16(file_get_contents('utf-16-le.txt')); // 1
* //
* UTF8::is_utf16(file_get_contents('utf-16-be.txt')); // 2
* //
* UTF8::is_utf16(file_get_contents('utf-8.txt')); // false
*
*
* @param string $str The input string.
* @param bool $check_if_string_is_binary * * @psalm-pure * * @return false|int * false if is't not UTF-16,
* UTF8::is_utf32(file_get_contents('utf-32-le.txt')); // 1
* //
* UTF8::is_utf32(file_get_contents('utf-32-be.txt')); // 2
* //
* UTF8::is_utf32(file_get_contents('utf-8.txt')); // false
*
*
* @param string $str The input string.
* @param bool $check_if_string_is_binary * * @psalm-pure * * @return false|int * false if is't not UTF-32,
* UTF8::is_utf8(['Iñtërnâtiônàlizætiøn', 'foo']); // true
* //
* UTF8::is_utf8(["Iñtërnâtiônàlizætiøn\xA0\xA1", 'bar']); // false
*
*
* @param int|string|string[]|null $str The input to be checked.
* @param bool $strictCheck also if the string is not UTF-16 or UTF-32.
* * @psalm-pure * * @return bool */ public static function is_utf8($str, bool $strict = false): bool { if (\is_array($str)) { foreach ($str as &$v) { if (!self::is_utf8($v, $strict)) { return false; } } return true; } return self::is_utf8_string((string) $str, $strict); } /** * (PHP 5 >= 5.2.0, PECL json >= 1.2.0)UTF8::json_decode('[1,"\u00a5","\u00e4"]'); // array(1, '¥', 'ä')
*
* @see http://php.net/manual/en/function.json-decode.php
*
* @param string $json * The json string being decoded. *
** This function only works with UTF-8 encoded strings. *
*PHP implements a superset of * JSON - it will also encode and decode scalar types and NULL. The JSON standard * only supports these values when they are nested inside an array or an object. *
* @param bool $assoc [optional]* When TRUE, returned objects will be converted into * associative arrays. *
* @param int $depth [optional]* User specified recursion depth. *
* @param int $options [optional]* Bitmask of JSON decode options. Currently only * JSON_BIGINT_AS_STRING * is supported (default is to cast large integers as floats) *
* * @psalm-pure * * @return mixed *The value encoded in json in appropriate PHP type. Values true, false and * null (case-insensitive) are returned as TRUE, FALSE and NULL respectively. * NULL is returned if the json cannot be decoded or if the encoded data * is deeper than the recursion limit.
*/ public static function json_decode( string $json, bool $assoc = false, int $depth = 512, int $options = 0 ) { $json = self::filter($json); if (self::$SUPPORT['json'] === false) { throw new \RuntimeException('ext-json: is not installed'); } if ($depth < 1) { $depth = 1; } return \json_decode($json, $assoc, $depth, $options); } /** * (PHP 5 >= 5.2.0, PECL json >= 1.2.0)UTF8::json_encode(array(1, '¥', 'ä')); // '[1,"\u00a5","\u00e4"]'
*
* @see http://php.net/manual/en/function.json-encode.php
*
* @param mixed $value * The value being encoded. Can be any type except * a resource. *
** All string data must be UTF-8 encoded. *
*PHP implements a superset of * JSON - it will also encode and decode scalar types and NULL. The JSON standard * only supports these values when they are nested inside an array or an object. *
* @param int $options [optional]* Bitmask consisting of JSON_HEX_QUOT, * JSON_HEX_TAG, * JSON_HEX_AMP, * JSON_HEX_APOS, * JSON_NUMERIC_CHECK, * JSON_PRETTY_PRINT, * JSON_UNESCAPED_SLASHES, * JSON_FORCE_OBJECT, * JSON_UNESCAPED_UNICODE. The behaviour of these * constants is described on * the JSON constants page. *
* @param int $depth [optional]* Set the maximum depth. Must be greater than zero. *
* * @psalm-pure * * @return false|string *A JSON encoded string on success or
* FALSE on failure.
true if available, false otherwise
* * @internalPlease do not use it anymore, we will make is private in next major version.
*/ public static function json_loaded(): bool { return \function_exists('json_decode'); } /** * Makes string's first char lowercase. * * EXAMPLE:UTF8::lcfirst('ÑTËRNÂTIÔNÀLIZÆTIØN'); // ñTËRNÂTIÔNÀLIZÆTIØN
*
* @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.
*/ public static function lcfirst( 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) { $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_strtolower( (string) \mb_substr($str, 0, 1) ); } else { $str_part_one = self::strtolower( (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); $str_part_one = self::strtolower( (string) self::substr($str, 0, 1, $encoding), $encoding, false, $lang, $try_to_keep_the_string_length ); } return $str_part_one . $str_part_two; } /** * Lowercase for all words in the string. * * @param string $strThe 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.
* @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 */ public static function lcwords( string $str, array $exceptions = [], string $char_list = '', string $encoding = 'UTF-8', bool $clean_utf8 = false, ?string $lang = null, bool $try_to_keep_the_string_length = false ): string { if (!$str) { return ''; } $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::lcfirst($word, $encoding, $clean_utf8, $lang, $try_to_keep_the_string_length); } else { $words_str .= $word; } } return $words_str; } /** * Calculate Levenshtein distance between two strings. * * For better performance, in a real application with a single input string * matched against many strings from a database, you will probably want to pre- * encode the input only once and use \levenshtein(). * * Source: https://github.com/KEINOS/mb_levenshtein * * @see https://www.php.net/manual/en/function.levenshtein * * @param string $str1One of the strings being evaluated for Levenshtein distance.
* @param string $str2One of the strings being evaluated for Levenshtein distance.
* @param int $insertionCost [optional]Defines the cost of insertion.
* @param int $replacementCost [optional]Defines the cost of replacement.
* @param int $deletionCost [optional]Defines the cost of deletion.
* * @return int */ public static function levenshtein( string $str1, string $str2, int $insertionCost = 1, int $replacementCost = 1, int $deletionCost = 1 ): int { $result = ASCII::to_ascii_remap($str1, $str2); return \levenshtein($result[0], $result[1], $insertionCost, $replacementCost, $deletionCost); } /** * Strip whitespace or other characters from the beginning of a UTF-8 string. * * EXAMPLE:UTF8::ltrim(' 中文空白 '); // '中文空白 '
*
* @param string $str The string to be trimmed
* @param string|null $charsOptional characters to be stripped
* * @psalm-pure * * @return string the string with unwanted characters stripped from the left */ public static function ltrim(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}]+"; } else { $pattern = '^[\\s]+'; } return (string) \mb_ereg_replace($pattern, '', $str); } if ($chars !== null) { $chars = \preg_quote($chars, '/'); $pattern = "^[{$chars}]+"; } else { $pattern = '^[\\s]+'; } return self::regex_replace($str, $pattern, ''); } /** * Returns the UTF-8 character with the maximum code point in the given data. * * EXAMPLE:UTF8::max('abc-äöü-中文空白'); // 'ø'
*
* @param string|string[] $arg A UTF-8 encoded string or an array of such strings.
* * @psalm-pure * * @return string|null the character with the highest code point than others, returns null on failure or empty input */ public static function max($arg) { if (\is_array($arg)) { $arg = \implode('', $arg); } $codepoints = self::codepoints($arg); if ($codepoints === []) { return null; } $codepoint_max = \max($codepoints); return self::chr((int) $codepoint_max); } /** * Calculates and returns the maximum number of bytes taken by any * UTF-8 encoded character in the given string. * * EXAMPLE:UTF8::max_chr_width('Intërnâtiônàlizætiøn'); // 2
*
* @param string $str The original Unicode string.
* * @psalm-pure * * @return int *Max byte lengths of the given chars.
* * @phpstan-return 0|1|2|3|4 */ public static function max_chr_width(string $str): int { $bytes = self::chr_size_list($str); if ($bytes !== []) { return (int) \max($bytes); } return 0; } /** * Checks whether mbstring is available on the server. * * @psalm-pure * * @return bool *true if available, false otherwise
* * @internalPlease do not use it anymore, we will make is private in next major version.
*/ public static function mbstring_loaded(): bool { return \extension_loaded('mbstring'); } /** * Returns the UTF-8 character with the minimum code point in the given data. * * EXAMPLE:UTF8::min('abc-äöü-中文空白'); // '-'
*
* @param string|string[] $arg A UTF-8 encoded string or an array of such strings.
*
* @psalm-pure
*
* @return string|null
* The character with the lowest code point than others, returns null on failure or empty input.
*/ public static function min($arg) { if (\is_array($arg)) { $arg = \implode('', $arg); } $codepoints = self::codepoints($arg); if ($codepoints === []) { return null; } $codepoint_min = \min($codepoints); return self::chr((int) $codepoint_min); } /** * Normalize the encoding-"name" input. * * EXAMPLE:UTF8::normalize_encoding('UTF8'); // 'UTF-8'
*
* @param mixed $encoding e.g.: ISO, UTF8, WINDOWS-1251 etc.
* @param mixed $fallbacke.g.: UTF-8
* * @psalm-pure * * @return mixed|string *e.g.: ISO-8859-1, UTF-8, WINDOWS-1251 etc.
Will return a empty string as fallback (by default)
The input string.
* @param string|string[] $replacerThe replacer char e.g. "\n" (Linux) or "\r\n" (Windows). You can also use \PHP_EOL * here.
* * @psalm-pure * * @return string *A string with normalized line ending.
*/ public static function normalize_line_ending(string $str, $replacer = "\n"): string { return \str_replace(["\r\n", "\r", "\n"], $replacer, $str); } /** * Normalize some MS Word special characters. * * EXAMPLE:UTF8::normalize_msword('„Abcdef…”'); // '"Abcdef..."'
*
* @param string $str The string to be normalized.
* * @psalm-pure * * @return string *A string with normalized characters for commonly used chars in Word documents.
*/ public static function normalize_msword(string $str): string { return ASCII::normalize_msword($str); } /** * Normalize the whitespace. * * EXAMPLE:UTF8::normalize_whitespace("abc-\xc2\xa0-öäü-\xe2\x80\xaf-\xE2\x80\xAC", true); // "abc-\xc2\xa0-öäü- -"
*
* @param string $str The string to be normalized.
* @param bool $keep_non_breaking_space [optional]Set to true, to keep non-breaking-spaces.
* @param bool $keep_bidi_unicode_controls [optional]Set to true, to keep non-printable (for the web) * bidirectional text chars.
* @param bool $normalize_control_characters [optional]Set to true, to convert e.g. LINE-, PARAGRAPH-SEPARATOR with "\n" and LINE TABULATION with "\t".
* * @psalm-pure * * @return string *A string with normalized whitespace.
*/ public static function normalize_whitespace( string $str, bool $keep_non_breaking_space = false, bool $keep_bidi_unicode_controls = false, bool $normalize_control_characters = false ): string { return ASCII::normalize_whitespace( $str, $keep_non_breaking_space, $keep_bidi_unicode_controls, $normalize_control_characters ); } /** * Calculates Unicode code point of the given UTF-8 encoded character. * * INFO: opposite to UTF8::chr() * * EXAMPLE:UTF8::ord('☃'); // 0x2603
*
* @param string $chr The character of which to calculate code point.
* @param string $encoding [optional]Set the charset for e.g. "mb_" function
* * @psalm-pure * * @return int *Unicode code point of the given character,
* 0 on invalid UTF-8 byte sequence
* UTF8::parse_str('Iñtërnâtiônéàlizætiøn=測試&arr[]=foo+測試&arr[]=ການທົດສອບ', $array);
* echo $array['Iñtërnâtiônéàlizætiøn']; // '測試'
*
*
* @see http://php.net/manual/en/function.parse-str.php
*
* @param string $str The input string.
* @param arrayThe result will be returned into this reference parameter.
* @param bool $clean_utf8 [optional]Remove non UTF-8 chars from the string.
* * @psalm-pure * * @return bool *Will return false if php can't parse the string and we haven't any $result.
*/ public static function parse_str(string $str, &$result, bool $clean_utf8 = false): bool { if ($clean_utf8) { $str = self::clean($str); } if (self::$SUPPORT['mbstring'] === true) { $return = \mb_parse_str($str, $result); return $return !== false && $result !== []; } /** * @psalm-suppress ImpureFunctionCall - we use the second parameter, so we don't change variables by magic */ \parse_str($str, $result); return $result !== []; } /** * Checks if \u modifier is available that enables Unicode support in PCRE. * * @psalm-pure * * @return bool *
* true if support is available,
* false otherwise
*
UTF8::range('κ', 'ζ'); // array('κ', 'ι', 'θ', 'η', 'ζ',)
*
* @param int|string $var1 Numeric or hexadecimal code points, or a UTF-8 character to start from.
* @param int|string $var2Numeric or hexadecimal code points, or a UTF-8 character to end at.
* @param bool $use_ctypeuse ctype to detect numeric and hexadecimal, otherwise we will use a simple * "is_numeric"
* @param string $encoding [optional]Set the charset for e.g. "mb_" function
* @param float|int $step [optional]* If a step value is given, it will be used as the * increment between elements in the sequence. step * should be given as a positive number. If not specified, * step will default to 1. *
* * @psalm-pure * * @return list$array['foo'][123] = 'lall'; UTF8::getUrlParamFromArray('foo[123]', $array); // 'lall'
*
* @param arrayUTF8::rawurldecode('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 *The decoded URL, as a string.
* * @template T as string * @phpstan-param T $str * @phpstan-return (T is non-empty-string ? non-empty-string : string) */ public static function rawurldecode(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 = \rawurldecode( self::html_entity_decode( self::to_utf8($str), \ENT_QUOTES | \ENT_HTML5 ) ); } while ($str_compare !== $str); } else { /** * @psalm-suppress PossiblyInvalidArgument */ $str = \rawurldecode( self::html_entity_decode( self::to_utf8($str), \ENT_QUOTES | \ENT_HTML5 ) ); } return self::fix_simple_utf8($str); } /** * Replaces all occurrences of $pattern in $str by $replacement. * * @param string $strThe input string.
* @param string $patternThe regular expression pattern.
* @param string $replacementThe string to replace with.
* @param string $options [optional]Matching conditions to be used.
* @param string $delimiter [optional]Delimiter the the regex. Default: '/'
* * @psalm-pure * * @return string */ public static function regex_replace( string $str, string $pattern, string $replacement, string $options = '', string $delimiter = '/' ): string { if ($options === 'msr') { $options = 'ms'; } // fallback if (!$delimiter) { $delimiter = '/'; } return (string) \preg_replace( $delimiter . $pattern . $delimiter . 'u' . $options, $replacement, $str ); } /** * Remove the BOM from UTF-8 / UTF-16 / UTF-32 strings. * * EXAMPLE:UTF8::remove_bom("\xEF\xBB\xBFΜπορώ να"); // 'Μπορώ να'
*
* @param string $str The input string.
* * @psalm-pure * * @return string *A string without UTF-BOM.
*/ public static function remove_bom(string $str): string { if ($str === '') { return ''; } $str_length = \strlen($str); foreach (self::$BOM as $bom_string => $bom_byte_length) { if (\strncmp($str, $bom_string, $bom_byte_length) === 0) { /** @var false|string $str_tmp - needed for PhpStan (stubs error) */ $str_tmp = \substr($str, $bom_byte_length, $str_length); if ($str_tmp === false) { return ''; } $str_length -= $bom_byte_length; $str = (string) $str_tmp; } } return $str; } /** * Removes duplicate occurrences of a string in another string. * * EXAMPLE:UTF8::remove_duplicates('öäü-κόσμεκόσμε-äöü', 'κόσμε'); // 'öäü-κόσμε-äöü'
*
* @param string $str The base string.
* @param string|string[] $whatString to search for in the base string.
* * @psalm-pure * * @return string *A string with removed duplicates.
*/ public static function remove_duplicates(string $str, $what = ' '): string { if (\is_string($what)) { $what = [$what]; } /** * @psalm-suppress RedundantConditionGivenDocblockType * @phpstan-ignore-next-line | ignore wrong inputs */ if (\is_array($what)) { foreach ($what as $item) { $str = (string) \preg_replace('/(' . \preg_quote($item, '/') . ')+/u', $item, $str); } } return $str; } /** * Remove html via "strip_tags()" from the string. * * @param string $strThe input string.
* @param string $allowable_tags [optional]You can use the optional second parameter to specify tags which * should not be stripped. Default: null *
* * @psalm-pure * * @return string *A string with without html tags.
*/ public static function remove_html(string $str, string $allowable_tags = ''): string { return \strip_tags($str, $allowable_tags); } /** * Remove all breaks [The input string.
* @param string $replacement [optional]Default is a empty string.
* * @psalm-pure * * @return string *A string without breaks.
*/ public static function remove_html_breaks(string $str, string $replacement = ''): string { return (string) \preg_replace("#/\r\n|\r|\n|UTF8::remove_invisible_characters("κόσ\0με"); // 'κόσμε'
*
* copy&past from https://github.com/bcit-ci/CodeIgniter/blob/develop/system/core/Common.php
*
* @param string $str The input string.
* @param bool $url_encoded [optional]
* Try to remove url encoded control character.
* WARNING: maybe contains false-positives e.g. aa%0Baa -> aaaa.
*
* Default: false
*
The replacement character.
* @param bool $keep_basic_control_characters [optional]Keep control characters like [LRM] or [LSEP].
* * @psalm-pure * * @return string *A string without invisible chars.
*/ public static function remove_invisible_characters( string $str, bool $url_encoded = false, string $replacement = '', bool $keep_basic_control_characters = true ): string { return ASCII::remove_invisible_characters( $str, $url_encoded, $replacement, $keep_basic_control_characters ); } /** * Returns a new string with the prefix $substring removed, if present. * * @param string $strThe input string.
* @param string $substringThe prefix to remove.
* @param string $encoding [optional]Default: 'UTF-8'
* * @psalm-pure * * @return string *A string without the prefix $substring.
*/ public static function remove_left( string $str, string $substring, string $encoding = 'UTF-8' ): string { if ( $substring && \strpos($str, $substring) === 0 ) { if ($encoding === 'UTF-8') { return (string) \mb_substr( $str, (int) \mb_strlen($substring) ); } $encoding = self::normalize_encoding($encoding, 'UTF-8'); return (string) self::substr( $str, (int) self::strlen($substring, $encoding), null, $encoding ); } return $str; } /** * Returns a new string with the suffix $substring removed, if present. * * @param string $str * @param string $substringThe suffix to remove.
* @param string $encoding [optional]Default: 'UTF-8'
* * @psalm-pure * * @return string *A string having a $str without the suffix $substring.
*/ public static function remove_right( string $str, string $substring, string $encoding = 'UTF-8' ): string { if ($substring && \substr($str, -\strlen($substring)) === $substring) { if ($encoding === 'UTF-8') { return (string) \mb_substr( $str, 0, (int) \mb_strlen($str) - (int) \mb_strlen($substring) ); } $encoding = self::normalize_encoding($encoding, 'UTF-8'); return (string) self::substr( $str, 0, (int) self::strlen($str, $encoding) - (int) self::strlen($substring, $encoding), $encoding ); } return $str; } /** * Returns a new string with the suffix $substring removed, if present and case-insensitive. * * @param string $str * @param string $substringThe suffix to remove.
* @param string $encoding [optional]Default: 'UTF-8'
* * @psalm-pure * * @return string *A string having a $str without the suffix $substring.
*/ public static function remove_iright( string $str, string $substring, string $encoding = 'UTF-8' ): string { if ($substring && self::strtoupper(\substr($str, -\strlen($substring)), $encoding) === self::strtoupper($substring, $encoding)) { if ($encoding === 'UTF-8') { return (string) \mb_substr( $str, 0, (int) \mb_strlen($str) - (int) \mb_strlen($substring) ); } $encoding = self::normalize_encoding($encoding, 'UTF-8'); return (string) self::substr( $str, 0, (int) self::strlen($str, $encoding) - (int) self::strlen($substring, $encoding), $encoding ); } return $str; } /** * Returns a new string with the prefix $substring removed, if present and case-insensitive. * * @param string $strThe input string.
* @param string $substringThe prefix to remove.
* @param string $encoding [optional]Default: 'UTF-8'
* * @psalm-pure * * @return string *A string without the prefix $substring.
*/ public static function remove_ileft( string $str, string $substring, string $encoding = 'UTF-8' ): string { if ( $substring && \strpos(self::strtoupper($str, $encoding), self::strtoupper($substring, $encoding)) === 0 ) { if ($encoding === 'UTF-8') { return (string) \mb_substr( $str, (int) \mb_strlen($substring) ); } $encoding = self::normalize_encoding($encoding, 'UTF-8'); return (string) self::substr( $str, (int) self::strlen($substring, $encoding), null, $encoding ); } return $str; } /** * Replaces all occurrences of $search in $str by $replacement. * * @param string $strThe input string.
* @param string $searchThe needle to search for.
* @param string $replacementThe string to replace with.
* @param bool $case_sensitive [optional]Whether or not to enforce case-sensitivity. Default: true
* * @psalm-pure * * @return string *A string with replaced parts.
*/ public static function replace( string $str, string $search, string $replacement, bool $case_sensitive = true ): string { if ($case_sensitive) { return \str_replace($search, $replacement, $str); } return self::str_ireplace($search, $replacement, $str); } /** * Replaces all occurrences of $search in $str by $replacement. * * @param string $strThe input string.
* @param string[] $searchThe elements to search for.
* @param string|string[] $replacementThe string to replace with.
* @param bool $case_sensitive [optional]Whether or not to enforce case-sensitivity. Default: true
* * @psalm-pure * * @return string *A string with replaced parts.
*/ public static function replace_all( string $str, array $search, $replacement, bool $case_sensitive = true ): string { if ($case_sensitive) { return \str_replace($search, $replacement, $str); } return self::str_ireplace($search, $replacement, $str); } /** * Replace the diamond question mark (�) and invalid-UTF8 chars with the replacement. * * EXAMPLE:UTF8::replace_diamond_question_mark('中文空白�', ''); // '中文空白'
*
* @param string $str The input string
* @param string $replacement_charThe replacement character.
* @param bool $process_invalid_utf8_charsConvert invalid UTF-8 chars
* * @psalm-pure * * @return string *A string without diamond question marks (�).
*/ public static function replace_diamond_question_mark( string $str, string $replacement_char = '', bool $process_invalid_utf8_chars = true ): string { if ($str === '') { return ''; } if ($process_invalid_utf8_chars) { if ($replacement_char === '') { $replacement_char_helper = 'none'; } else { $replacement_char_helper = \ord($replacement_char); } if (self::$SUPPORT['mbstring'] === false) { // if there is no native support for "mbstring", // then we need to clean the string before ... $str = self::clean($str); } /** * @psalm-suppress ImpureFunctionCall - we will reset the value in the next step */ $save = \mb_substitute_character(); /** @noinspection PhpUsageOfSilenceOperatorInspection - ignore "Unknown character" warnings, it's working anyway */ @\mb_substitute_character($replacement_char_helper); // the polyfill maybe return false, so cast to string $str = (string) \mb_convert_encoding($str, 'UTF-8', 'UTF-8'); \mb_substitute_character($save); } return \str_replace( [ "\xEF\xBF\xBD", '�', ], [ $replacement_char, $replacement_char, ], $str ); } /** * Strip whitespace or other characters from the end of a UTF-8 string. * * EXAMPLE:UTF8::rtrim('-ABC-中文空白- '); // '-ABC-中文空白-'
*
* @param string $str The string to be trimmed.
* @param string|null $charsOptional characters to be stripped.
* * @psalm-pure * * @return string *A string with unwanted characters stripped from the right.
*/ public static function rtrim(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}]+$"; } else { $pattern = '[\\s]+$'; } return (string) \mb_ereg_replace($pattern, '', $str); } if ($chars !== null) { $chars = \preg_quote($chars, '/'); $pattern = "[{$chars}]+$"; } else { $pattern = '[\\s]+$'; } return self::regex_replace($str, $pattern, ''); } /** * WARNING: Print native UTF-8 support (libs) by default, e.g. for debugging. * * @param bool $useEcho * * @psalm-pure * * @return string|void * * @phpstan-return ($useEcho is true ? void : string) */ public static function showSupport(bool $useEcho = true) { // init $html = ''; $html .= '';
foreach (self::$SUPPORT as $key => &$value) {
$html .= $key . ' - ' . \print_r($value, true) . "\n
";
}
$html .= '';
if ($useEcho) {
echo $html;
}
return $html;
}
/**
* Converts a UTF-8 character to HTML Numbered Entity like "{".
*
* EXAMPLE: UTF8::single_chr_html_encode('κ'); // 'κ'
*
* @param string $char The Unicode character to be encoded as numbered entity.
* @param bool $keep_ascii_charsSet to true to keep ASCII chars. * @param string $encoding [optional]
Set the charset for e.g. "mb_" function
* * @psalm-pure * * @return string *The HTML numbered entity for the given character.
* * @template T as string * @phpstan-param T $char * @phpstan-return (T is non-empty-string ? non-empty-string : string) */ public static function single_chr_html_encode( string $char, bool $keep_ascii_chars = false, string $encoding = 'UTF-8' ): string { if ($char === '') { return ''; } if ( $keep_ascii_chars && ASCII::is_ascii($char) ) { return $char; } return '&#' . self::ord($char, $encoding) . ';'; } /** * @param string $str * @param int<1, max> $tab_length * * @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 spaces_to_tabs(string $str, int $tab_length = 4): string { if ($tab_length === 4) { $tab = ' '; } elseif ($tab_length === 2) { $tab = ' '; } else { $tab = \str_repeat(' ', $tab_length); } return \str_replace($tab, "\t", $str); } /** * Returns a camelCase version of the string. Trims surrounding spaces, * capitalizes letters following digits, spaces, dashes and underscores, * and removes spaces, dashes, as well as underscores. * * @param string $strThe input string.
* @param string $encoding [optional]Default: 'UTF-8'
* @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 */ public static function str_camelize( 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) { $str = self::clean($str); } if ($encoding !== 'UTF-8' && $encoding !== 'CP850') { $encoding = self::normalize_encoding($encoding, 'UTF-8'); } $str = self::lcfirst( \trim($str), $encoding, false, $lang, $try_to_keep_the_string_length ); $str = (string) \preg_replace('/^[-_]+/', '', $str); $use_mb_functions = $lang === null && !$try_to_keep_the_string_length; $str = (string) \preg_replace_callback( '/[-_\\s]+(.)?/u', /** * @param array $match * * @psalm-pure * * @return string */ static function (array $match) use ($use_mb_functions, $encoding, $lang, $try_to_keep_the_string_length): string { if (isset($match[1])) { if ($use_mb_functions) { if ($encoding === 'UTF-8') { return \mb_strtoupper($match[1]); } return \mb_strtoupper($match[1], $encoding); } return self::strtoupper($match[1], $encoding, false, $lang, $try_to_keep_the_string_length); } return ''; }, $str ); return (string) \preg_replace_callback( '/[\\p{N}]+(.)?/u', /** * @param array $match * * @psalm-pure * * @return string */ static function (array $match) use ($use_mb_functions, $encoding, $clean_utf8, $lang, $try_to_keep_the_string_length): string { if ($use_mb_functions) { if ($encoding === 'UTF-8') { return \mb_strtoupper($match[0]); } return \mb_strtoupper($match[0], $encoding); } return self::strtoupper($match[0], $encoding, $clean_utf8, $lang, $try_to_keep_the_string_length); }, $str ); } /** * Returns the string with the first letter of each word capitalized, * except for when the word is a name which shouldn't be capitalized. * * @param string $str * * @psalm-pure * * @return string *A string with $str capitalized.
*/ public static function str_capitalize_name(string $str): string { return self::str_capitalize_name_helper( self::str_capitalize_name_helper( self::collapse_whitespace($str), ' ' ), '-' ); } /** * Returns true if the string contains $needle, false otherwise. By default * the comparison is case-sensitive, but can be made insensitive by setting * $case_sensitive to false. * * @param string $haystackThe input string.
* @param string $needleSubstring to look for.
* @param bool $case_sensitive [optional]Whether or not to enforce case-sensitivity. Default: true
* * @psalm-pure * * @return bool *Whether or not $haystack contains $needle.
*/ public static function str_contains( string $haystack, string $needle, bool $case_sensitive = true ): bool { if ($case_sensitive) { if (\PHP_VERSION_ID >= 80000) { /** @phpstan-ignore-next-line - only for PHP8 */ return \str_contains($haystack, $needle); } return \strpos($haystack, $needle) !== false; } return \mb_stripos($haystack, $needle) !== false; } /** * Returns true if the string contains all $needles, false otherwise. By * default, the comparison is case-sensitive, but can be made insensitive by * setting $case_sensitive to false. * * @param string $haystackThe input string.
* @param scalar[] $needlesSubStrings to look for.
* @param bool $case_sensitive [optional]Whether or not to enforce case-sensitivity. Default: true
* * @psalm-pure * * @return bool *Whether or not $haystack contains $needle.
*/ public static function str_contains_all( string $haystack, array $needles, bool $case_sensitive = true ): bool { if ($haystack === '' || $needles === []) { return false; } foreach ($needles as &$needle) { if ( $case_sensitive && (!$needle || \strpos($haystack, (string)$needle) === false) ) { return false; } if (!$needle || \mb_stripos($haystack, (string) $needle) === false) { return false; } } return true; } /** * Returns true if the string contains any $needles, false otherwise. By * default the comparison is case-sensitive, but can be made insensitive by * setting $case_sensitive to false. * * @param string $haystackThe input string.
* @param scalar[] $needlesSubStrings to look for.
* @param bool $case_sensitive [optional]Whether or not to enforce case-sensitivity. Default: true
* * @psalm-pure * * @return bool *Whether or not $str contains $needle.
*/ public static function str_contains_any( string $haystack, array $needles, bool $case_sensitive = true ): bool { if ($haystack === '' || $needles === []) { return false; } foreach ($needles as &$needle) { if (!$needle) { continue; } if ($case_sensitive) { if (\strpos($haystack, (string) $needle) !== false) { return true; } continue; } if (\mb_stripos($haystack, (string) $needle) !== false) { return true; } } return false; } /** * Returns a lowercase and trimmed string separated by dashes. Dashes are * inserted before uppercase characters (with the exception of the first * character of the string), and in place of spaces as well as underscores. * * @param string $strThe input string.
* @param string $encoding [optional]Set the charset for e.g. "mb_" function
* * @psalm-pure * * @return string */ public static function str_dasherize(string $str, string $encoding = 'UTF-8'): string { return self::str_delimit($str, '-', $encoding); } /** * Returns a lowercase and trimmed string separated by the given delimiter. * * Delimiters are inserted before uppercase characters (with the exception * of the first character of the string), and in place of spaces, dashes, * and underscores. Alpha delimiters are not converted to lowercase. * * EXAMPLE:
* UTF8::str_delimit('test case, '#'); // 'test#case'
* UTF8::str_delimit('test -case', '**'); // 'test**case'
*
*
* @param string $str The input string.
* @param string $delimiterSequence used to separate parts of the 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 * * @template T as string * @phpstan-param T $str * @phpstan-return (T is non-empty-string ? non-empty-string : string) */ public static function str_delimit( string $str, string $delimiter, string $encoding = 'UTF-8', bool $clean_utf8 = false, ?string $lang = null, bool $try_to_keep_the_string_length = false ): string { if (self::$SUPPORT['mbstring'] === true) { $str = (string) \mb_ereg_replace('\\B(\\p{Lu})', '-\1', \trim($str)); $use_mb_functions = $lang === null && !$try_to_keep_the_string_length; if ($use_mb_functions && $encoding === 'UTF-8') { $str = \mb_strtolower($str); } else { $str = self::strtolower($str, $encoding, $clean_utf8, $lang, $try_to_keep_the_string_length); } return (string) \mb_ereg_replace('[\\-_\\s]+', $delimiter, $str); } $str = (string) \preg_replace('/\\B(\\p{Lu})/u', '-\1', \trim($str)); $use_mb_functions = $lang === null && !$try_to_keep_the_string_length; if ($use_mb_functions && $encoding === 'UTF-8') { $str = \mb_strtolower($str); } else { $str = self::strtolower($str, $encoding, $clean_utf8, $lang, $try_to_keep_the_string_length); } return (string) \preg_replace('/[\\-_\\s]+/u', $delimiter, $str); } /** * Optimized "mb_detect_encoding()"-function -> with support for UTF-16 and UTF-32. * * EXAMPLE:
* UTF8::str_detect_encoding('中文空白'); // 'UTF-8'
* UTF8::str_detect_encoding('Abc'); // 'ASCII'
*
*
* @param string $str The input string.
* * @psalm-pure * * @return false|string *
* The detected string-encoding e.g. UTF-8 or UTF-16BE,
* otherwise it will return false e.g. for BINARY or not detected encoding.
*
* UTF8::str_ends_with('BeginMiddleΚόσμε', 'Κόσμε'); // true
* UTF8::str_ends_with('BeginMiddleΚόσμε', 'κόσμε'); // false
*
*
* @param string $haystack The string to search in.
* @param string $needleThe substring to search for.
* * @psalm-pure * * @return bool */ public static function str_ends_with(string $haystack, string $needle): bool { if ($needle === '') { return true; } if ($haystack === '') { return false; } if (\PHP_VERSION_ID >= 80000) { /** @phpstan-ignore-next-line - only for PHP8 */ return \str_ends_with($haystack, $needle); } return \substr($haystack, -\strlen($needle)) === $needle; } /** * Returns true if the string ends with any of $substrings, false otherwise. * * - case-sensitive * * @param string $strThe input string.
* @param string[] $substringsSubstrings to look for.
* * @psalm-pure * * @return bool *Whether or not $str ends with $substring.
*/ public static function str_ends_with_any(string $str, array $substrings): bool { if ($substrings === []) { return false; } foreach ($substrings as &$substring) { if (\substr($str, -\strlen($substring)) === $substring) { return true; } } return false; } /** * Ensures that the string begins with $substring. If it doesn't, it's * prepended. * * @param string $strThe input string.
* @param string $substringThe substring to add if not present.
* * @psalm-pure * * @template T as string * @template TSub as string * @phpstan-param T $str * @phpstan-param TSub $substring * @phpstan-return (TSub is non-empty-string ? non-empty-string : (T is non-empty-string ? non-empty-string : string)) */ public static function str_ensure_left(string $str, string $substring): string { if ( $substring !== '' && \strpos($str, $substring) === 0 ) { return $str; } return $substring . $str; } /** * Ensures that the string ends with $substring. If it doesn't, it's appended. * * @param string $strThe input string.
* @param string $substringThe substring to add if not present.
* * @psalm-pure * * @return string * * @template T as string * @template TSub as string * @phpstan-param T $str * @phpstan-param TSub $substring * @phpstan-return (TSub is non-empty-string ? non-empty-string : (T is non-empty-string ? non-empty-string : string)) */ public static function str_ensure_right(string $str, string $substring): string { if ( $str === '' || $substring === '' || \substr($str, -\strlen($substring)) !== $substring ) { $str .= $substring; } return $str; } /** * Capitalizes the first word of the string, replaces underscores with * spaces, and strips '_id'. * * @param string $str * * @psalm-pure * * @return string */ public static function str_humanize($str): string { $str = \str_replace( [ '_id', '_', ], [ '', ' ', ], $str ); return self::ucfirst(\trim($str)); } /** * Check if the string ends with the given substring, case-insensitive. * * EXAMPLE:
* UTF8::str_iends_with('BeginMiddleΚόσμε', 'Κόσμε'); // true
* UTF8::str_iends_with('BeginMiddleΚόσμε', 'κόσμε'); // true
*
*
* @param string $haystack The string to search in.
* @param string $needleThe substring to search for.
* * @psalm-pure * * @return bool */ public static function str_iends_with(string $haystack, string $needle): bool { if ($needle === '') { return true; } if ($haystack === '') { return false; } return self::strcasecmp(\substr($haystack, -\strlen($needle)), $needle) === 0; } /** * Returns true if the string ends with any of $substrings, false otherwise. * * - case-insensitive * * @param string $strThe input string.
* @param string[] $substringsSubstrings to look for.
* * @psalm-pure * * @return bool *Whether or not $str ends with $substring.
*/ public static function str_iends_with_any(string $str, array $substrings): bool { if ($substrings === []) { return false; } foreach ($substrings as &$substring) { if (self::str_iends_with($str, $substring)) { return true; } } return false; } /** * Inserts $substring into the string at the $index provided. * * @param string $strThe input string.
* @param string $substringString to be inserted.
* @param int $indexThe index at which to insert the substring.
* @param string $encoding [optional]Set the charset for e.g. "mb_" function
* * @psalm-pure * * @return string */ public static function str_insert( string $str, string $substring, int $index, string $encoding = 'UTF-8' ): string { if ($encoding === 'UTF-8') { $len = (int) \mb_strlen($str); if ($index > $len) { return $str; } /** @noinspection UnnecessaryCastingInspection */ return (string) \mb_substr($str, 0, $index) . $substring . (string) \mb_substr($str, $index, $len); } $encoding = self::normalize_encoding($encoding, 'UTF-8'); $len = (int) self::strlen($str, $encoding); if ($index > $len) { return $str; } return ((string) self::substr($str, 0, $index, $encoding)) . $substring . ((string) self::substr($str, $index, $len, $encoding)); } /** * Case-insensitive and UTF-8 safe version of
* UTF8::str_ireplace('lIzÆ', 'lise', 'Iñtërnâtiônàlizætiøn'); // 'Iñtërnâtiônàlisetiøn'
*
*
* @see http://php.net/manual/en/function.str-ireplace.php
*
* @param string|string[] $search * Every replacement with search array is * performed on the result of previous replacement. *
* @param string|string[] $replacementThe replacement.
* @param string|string[] $subject* If subject is an array, then the search and * replace is performed with every entry of * subject, and the return value is an array as * well. *
* @param int $count [optional]* The number of matched and replaced needles will * be returned in count which is passed by * reference. *
* * @psalm-pure * * @return string|string[] *A string or an array of replacements.
* * @template TStrIReplaceSubject * @phpstan-param TStrIReplaceSubject $subject * @phpstan-return TStrIReplaceSubject */ public static function str_ireplace($search, $replacement, $subject, &$count = null) { $search = (array) $search; /** @noinspection AlterInForeachInspection */ foreach ($search as &$s) { $s = (string) $s; if ($s === '') { $s = '/^(?<=.)$/'; } else { $s = '/' . \preg_quote($s, '/') . '/ui'; } } // fallback /** @phpstan-ignore-next-line - only a fallback for PHP8 */ if ($replacement === null) { $replacement = ''; } /** @phpstan-ignore-next-line - only a fallback for PHP8 */ if ($subject === null) { $subject = ''; } /** * @psalm-suppress PossiblyNullArgument * @phpstan-var TStrIReplaceSubject $subject */ $subject = \preg_replace($search, $replacement, $subject, -1, $count); return $subject; } /** * Replaces $search from the beginning of string with $replacement. * * @param string $strThe input string.
* @param string $searchThe string to search for.
* @param string $replacementThe replacement.
* * @psalm-pure * * @return string *The string after the replacement.
*/ public static function str_ireplace_beginning(string $str, string $search, string $replacement): string { if ($str === '') { if ($replacement === '') { return ''; } if ($search === '') { return $replacement; } } if ($search === '') { return $str . $replacement; } $searchLength = \strlen($search); if (\strncasecmp($str, $search, $searchLength) === 0) { return $replacement . \substr($str, $searchLength); } return $str; } /** * Replaces $search from the ending of string with $replacement. * * @param string $strThe input string.
* @param string $searchThe string to search for.
* @param string $replacementThe replacement.
* * @psalm-pure * * @return string *The string after the replacement.
*/ public static function str_ireplace_ending(string $str, string $search, string $replacement): string { if ($str === '') { if ($replacement === '') { return ''; } if ($search === '') { return $replacement; } } if ($search === '') { return $str . $replacement; } if (\stripos($str, $search, \strlen($str) - \strlen($search)) !== false) { $str = \substr($str, 0, -\strlen($search)) . $replacement; } return $str; } /** * Check if the string starts with the given substring, case-insensitive. * * EXAMPLE:
* UTF8::str_istarts_with('ΚόσμεMiddleEnd', 'Κόσμε'); // true
* UTF8::str_istarts_with('ΚόσμεMiddleEnd', 'κόσμε'); // true
*
*
* @param string $haystack The string to search in.
* @param string $needleThe substring to search for.
* * @psalm-pure * * @return bool */ public static function str_istarts_with(string $haystack, string $needle): bool { if ($needle === '') { return true; } if ($haystack === '') { return false; } return self::stripos($haystack, $needle) === 0; } /** * Returns true if the string begins with any of $substrings, false otherwise. * * - case-insensitive * * @param string $strThe input string.
* @param scalar[] $substringsSubstrings to look for.
* * @psalm-pure * * @return bool *Whether or not $str starts with $substring.
*/ public static function str_istarts_with_any(string $str, array $substrings): bool { if ($str === '') { return false; } if ($substrings === []) { return false; } foreach ($substrings as &$substring) { if (self::str_istarts_with($str, (string) $substring)) { return true; } } return false; } /** * Gets the substring after the first occurrence of a separator. * * @param string $strThe input string.
* @param string $separatorThe string separator.
* @param string $encoding [optional]Default: 'UTF-8'
* * @psalm-pure * * @return string */ public static function str_isubstr_after_first_separator( string $str, string $separator, string $encoding = 'UTF-8' ): string { if ($separator === '' || $str === '') { return ''; } $offset = self::stripos($str, $separator); if ($offset === false) { return ''; } if ($encoding === 'UTF-8') { return (string) \mb_substr( $str, $offset + (int) \mb_strlen($separator) ); } return (string) self::substr( $str, $offset + (int) self::strlen($separator, $encoding), null, $encoding ); } /** * Gets the substring after the last occurrence of a separator. * * @param string $strThe input string.
* @param string $separatorThe string separator.
* @param string $encoding [optional]Default: 'UTF-8'
* * @psalm-pure * * @return string */ public static function str_isubstr_after_last_separator( string $str, string $separator, string $encoding = 'UTF-8' ): string { if ($separator === '' || $str === '') { return ''; } $offset = self::strripos($str, $separator); if ($offset === false) { return ''; } if ($encoding === 'UTF-8') { return (string) \mb_substr( $str, $offset + (int) self::strlen($separator) ); } return (string) self::substr( $str, $offset + (int) self::strlen($separator, $encoding), null, $encoding ); } /** * Gets the substring before the first occurrence of a separator. * * @param string $strThe input string.
* @param string $separatorThe string separator.
* @param string $encoding [optional]Default: 'UTF-8'
* * @psalm-pure * * @return string */ public static function str_isubstr_before_first_separator( string $str, string $separator, string $encoding = 'UTF-8' ): string { if ($separator === '' || $str === '') { return ''; } $offset = self::stripos($str, $separator); if ($offset === false) { return ''; } if ($encoding === 'UTF-8') { return (string) \mb_substr($str, 0, $offset); } return (string) self::substr($str, 0, $offset, $encoding); } /** * Gets the substring before the last occurrence of a separator. * * @param string $strThe input string.
* @param string $separatorThe string separator.
* @param string $encoding [optional]Default: 'UTF-8'
* * @psalm-pure * * @return string */ public static function str_isubstr_before_last_separator( string $str, string $separator, string $encoding = 'UTF-8' ): string { if ($separator === '' || $str === '') { return ''; } if ($encoding === 'UTF-8') { $offset = \mb_strripos($str, $separator); if ($offset === false) { return ''; } return (string) \mb_substr($str, 0, $offset); } $offset = self::strripos($str, $separator, 0, $encoding); if ($offset === false) { return ''; } return (string) self::substr($str, 0, $offset, $encoding); } /** * Gets the substring after (or before via "$before_needle") the first occurrence of the "$needle". * * @param string $strThe input string.
* @param string $needleThe string to look for.
* @param bool $before_needle [optional]Default: false
* @param string $encoding [optional]Default: 'UTF-8'
* * @psalm-pure * * @return string */ public static function str_isubstr_first( string $str, string $needle, bool $before_needle = false, string $encoding = 'UTF-8' ): string { if ( $needle === '' || $str === '' ) { return ''; } $part = self::stristr( $str, $needle, $before_needle, $encoding ); if ($part === false) { return ''; } return $part; } /** * Gets the substring after (or before via "$before_needle") the last occurrence of the "$needle". * * @param string $strThe input string.
* @param string $needleThe string to look for.
* @param bool $before_needle [optional]Default: false
* @param string $encoding [optional]Default: 'UTF-8'
* * @psalm-pure * * @return string */ public static function str_isubstr_last( string $str, string $needle, bool $before_needle = false, string $encoding = 'UTF-8' ): string { if ( $needle === '' || $str === '' ) { return ''; } $part = self::strrichr( $str, $needle, $before_needle, $encoding ); if ($part === false) { return ''; } return $part; } /** * Returns the last $n characters of the string. * * @param string $strThe input string.
* @param int $nNumber of characters to retrieve from the end.
* @param string $encoding [optional]Set the charset for e.g. "mb_" function
* * @psalm-pure * * @return string */ public static function str_last_char( string $str, int $n = 1, string $encoding = 'UTF-8' ): string { if ($str === '' || $n <= 0) { return ''; } if ($encoding === 'UTF-8') { return (string) \mb_substr($str, -$n); } $encoding = self::normalize_encoding($encoding, 'UTF-8'); return (string) self::substr($str, -$n, null, $encoding); } /** * Limit the number of characters in a string. * * @param string $strThe input string.
* @param int<1, max> $length [optional]Default: 100
* @param string $str_add_on [optional]Default: …
* @param string $encoding [optional]Set the charset for e.g. "mb_" function
* * @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 str_limit( string $str, int $length = 100, string $str_add_on = '…', string $encoding = 'UTF-8' ): string { if ( $str === '' || /* @phpstan-ignore-next-line | we do not trust the phpdoc check */ $length <= 0 ) { return ''; } if ($encoding === 'UTF-8') { if ((int) \mb_strlen($str) <= $length) { return $str; } /** @noinspection UnnecessaryCastingInspection */ return (string) \mb_substr($str, 0, $length - (int) self::strlen($str_add_on)) . $str_add_on; } $encoding = self::normalize_encoding($encoding, 'UTF-8'); if ((int) self::strlen($str, $encoding) <= $length) { return $str; } return ((string) self::substr($str, 0, $length - (int) self::strlen($str_add_on), $encoding)) . $str_add_on; } /** * Limit the number of characters in a string in bytes. * * @param string $strThe input string.
* @param int<1, max> $length [optional]Default: 100
* @param string $str_add_on [optional]Default: ...
* @param string $encoding [optional]Set the charset for e.g. "mb_" function
* * @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 str_limit_in_byte( string $str, int $length = 100, string $str_add_on = '...', string $encoding = 'UTF-8' ): string { if ( $str === '' || /* @phpstan-ignore-next-line | we do not trust the phpdoc check */ $length <= 0 ) { return ''; } $encoding = self::normalize_encoding($encoding, 'UTF-8'); if ((int) self::strlen_in_byte($str, $encoding) <= $length) { return $str; } return ((string) self::substr_in_byte($str, 0, $length - (int) self::strlen_in_byte($str_add_on), $encoding)) . $str_add_on; } /** * Limit the number of characters in a string, but also after the next word. * * EXAMPLE:UTF8::str_limit_after_word('fòô bàř fòô', 8, ''); // 'fòô bàř'
*
* @param string $str The input string.
* @param int<1, max> $length [optional]Default: 100
* @param string $str_add_on [optional]Default: …
* @param string $encoding [optional]Set the charset for e.g. "mb_" function
* * @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 str_limit_after_word( string $str, int $length = 100, string $str_add_on = '…', string $encoding = 'UTF-8' ): string { if ( $str === '' || /* @phpstan-ignore-next-line | we do not trust the phpdoc check */ $length <= 0 ) { return ''; } if ($encoding === 'UTF-8') { if ((int) \mb_strlen($str) <= $length) { return $str; } if (\mb_substr($str, $length - 1, 1) === ' ') { return ((string) \mb_substr($str, 0, $length - 1)) . $str_add_on; } $str = \mb_substr($str, 0, $length); $array = \explode(' ', $str, -1); $new_str = \implode(' ', $array); if ($new_str === '') { return ((string) \mb_substr($str, 0, $length - 1)) . $str_add_on; } } else { if ((int) self::strlen($str, $encoding) <= $length) { return $str; } if (self::substr($str, $length - 1, 1, $encoding) === ' ') { return ((string) self::substr($str, 0, $length - 1, $encoding)) . $str_add_on; } /** @noinspection CallableParameterUseCaseInTypeContextInspection - FP */ $str = self::substr($str, 0, $length, $encoding); if ($str === false) { return '' . $str_add_on; } $array = \explode(' ', $str, -1); $new_str = \implode(' ', $array); if ($new_str === '') { return ((string) self::substr($str, 0, $length - 1, $encoding)) . $str_add_on; } } return $new_str . $str_add_on; } /** * Returns the longest common prefix between the $str1 and $str2. * * @param string $str1The input sting.
* @param string $str2Second string for comparison.
* @param string $encoding [optional]Set the charset for e.g. "mb_" function
* * @psalm-pure * * @return string */ public static function str_longest_common_prefix( string $str1, string $str2, string $encoding = 'UTF-8' ): string { // init $longest_common_prefix = ''; if ($encoding === 'UTF-8') { $max_length = (int) \min( \mb_strlen($str1), \mb_strlen($str2) ); for ($i = 0; $i < $max_length; ++$i) { $char = \mb_substr($str1, $i, 1); if ( $char !== false /* @phpstan-ignore-line | old polyfill will return false, or? */ && $char === \mb_substr($str2, $i, 1) ) { $longest_common_prefix .= $char; } else { break; } } } else { $encoding = self::normalize_encoding($encoding, 'UTF-8'); $max_length = (int) \min( self::strlen($str1, $encoding), self::strlen($str2, $encoding) ); for ($i = 0; $i < $max_length; ++$i) { $char = self::substr($str1, $i, 1, $encoding); if ( $char !== false && $char === self::substr($str2, $i, 1, $encoding) ) { $longest_common_prefix .= $char; } else { break; } } } return $longest_common_prefix; } /** * Returns the longest common substring between the $str1 and $str2. * In the case of ties, it returns that which occurs first. * * @param string $str1 * @param string $str2Second string for comparison.
* @param string $encoding [optional]Set the charset for e.g. "mb_" function
* * @psalm-pure * * @return string *A string with its $str being the longest common substring.
*/ public static function str_longest_common_substring( string $str1, string $str2, string $encoding = 'UTF-8' ): string { if ($str1 === '' || $str2 === '') { return ''; } // Uses dynamic programming to solve // http://en.wikipedia.org/wiki/Longest_common_substring_problem if ($encoding === 'UTF-8') { $str_length = (int) \mb_strlen($str1); $other_length = (int) \mb_strlen($str2); } else { $encoding = self::normalize_encoding($encoding, 'UTF-8'); $str_length = (int) self::strlen($str1, $encoding); $other_length = (int) self::strlen($str2, $encoding); } // Return if either string is empty if ($str_length === 0 || $other_length === 0) { return ''; } $len = 0; $end = 0; $table = \array_fill( 0, $str_length + 1, \array_fill(0, $other_length + 1, 0) ); if ($encoding === 'UTF-8') { for ($i = 1; $i <= $str_length; ++$i) { for ($j = 1; $j <= $other_length; ++$j) { $str_char = \mb_substr($str1, $i - 1, 1); $other_char = \mb_substr($str2, $j - 1, 1); if ($str_char === $other_char) { $table[$i][$j] = $table[$i - 1][$j - 1] + 1; if ($table[$i][$j] > $len) { $len = $table[$i][$j]; $end = $i; } } else { $table[$i][$j] = 0; } } } } else { for ($i = 1; $i <= $str_length; ++$i) { for ($j = 1; $j <= $other_length; ++$j) { $str_char = self::substr($str1, $i - 1, 1, $encoding); $other_char = self::substr($str2, $j - 1, 1, $encoding); if ($str_char === $other_char) { $table[$i][$j] = $table[$i - 1][$j - 1] + 1; if ($table[$i][$j] > $len) { $len = $table[$i][$j]; $end = $i; } } else { $table[$i][$j] = 0; } } } } if ($encoding === 'UTF-8') { return (string) \mb_substr($str1, $end - $len, $len); } return (string) self::substr($str1, $end - $len, $len, $encoding); } /** * Returns the longest common suffix between the $str1 and $str2. * * @param string $str1 * @param string $str2Second string for comparison.
* @param string $encoding [optional]Set the charset for e.g. "mb_" function
* * @psalm-pure * * @return string */ public static function str_longest_common_suffix( string $str1, string $str2, string $encoding = 'UTF-8' ): string { if ($str1 === '' || $str2 === '') { return ''; } if ($encoding === 'UTF-8') { $max_length = (int) \min( \mb_strlen($str1, $encoding), \mb_strlen($str2, $encoding) ); $longest_common_suffix = ''; for ($i = 1; $i <= $max_length; ++$i) { $char = \mb_substr($str1, -$i, 1); if ( $char !== false /* @phpstan-ignore-line | old polyfill will return false, or? */ && $char === \mb_substr($str2, -$i, 1) ) { $longest_common_suffix = $char . $longest_common_suffix; } else { break; } } } else { $encoding = self::normalize_encoding($encoding, 'UTF-8'); $max_length = (int) \min( self::strlen($str1, $encoding), self::strlen($str2, $encoding) ); $longest_common_suffix = ''; for ($i = 1; $i <= $max_length; ++$i) { $char = self::substr($str1, -$i, 1, $encoding); if ( $char !== false && $char === self::substr($str2, -$i, 1, $encoding) ) { $longest_common_suffix = $char . $longest_common_suffix; } else { break; } } } return $longest_common_suffix; } /** * Returns true if $str matches the supplied pattern, false otherwise. * * @param string $strThe input string.
* @param string $patternRegex pattern to match against.
* * @psalm-pure * * @return bool *Whether or not $str matches the pattern.
*/ public static function str_matches_pattern(string $str, string $pattern): bool { return (bool) \preg_match('/' . $pattern . '/u', $str); } /** * Returns whether or not a character exists at an index. Offsets may be * negative to count from the last character in the string. Implements * part of the ArrayAccess interface. * * @param string $strThe input string.
* @param int $offsetThe index to check.
* @param string $encoding [optional]Set the charset for e.g. "mb_" function
* * @psalm-pure * * @return bool *Whether or not the index exists.
*/ public static function str_offset_exists(string $str, int $offset, string $encoding = 'UTF-8'): bool { // init $length = (int) self::strlen($str, $encoding); if ($offset >= 0) { return $length > $offset; } return $length >= \abs($offset); } /** * Returns the character at the given index. Offsets may be negative to * count from the last character in the string. Implements part of the * ArrayAccess interface, and throws an OutOfBoundsException if the index * does not exist. * * @param string $strThe input string.
* @param int<1, max> $indexThe index from which to retrieve the char.
* @param string $encoding [optional]Set the charset for e.g. "mb_" function
* * @throws \OutOfBoundsException if the positive or negative offset does not exist * * @return string *The character at the specified index.
* * @psalm-pure */ public static function str_offset_get(string $str, int $index, string $encoding = 'UTF-8'): string { // init $length = (int) self::strlen($str); if ( /* @phpstan-ignore-next-line | we do not trust the phpdoc check */ ($index >= 0 && $length <= $index) || $length < \abs($index) ) { throw new \OutOfBoundsException('No character exists at the index'); } return self::char_at($str, $index, $encoding); } /** * Pad a UTF-8 string to a given length with another string. * * EXAMPLE:UTF8::str_pad('中文空白', 10, '_', STR_PAD_BOTH); // '___中文空白___'
*
* @param string $str The input string.
* @param int $pad_lengthThe length of return string.
* @param string $pad_string [optional]String to use for padding the input string.
* @param int|string $pad_type [optional]
* Can be STR_PAD_RIGHT (default), [or string "right"]
* STR_PAD_LEFT [or string "left"] or
* STR_PAD_BOTH [or string "both"]
*
Default: 'UTF-8'
* * @psalm-pure * * @return string *Returns the padded string.
*/ public static function str_pad( string $str, int $pad_length, string $pad_string = ' ', $pad_type = \STR_PAD_RIGHT, string $encoding = 'UTF-8' ): string { if ($pad_length === 0 || $pad_string === '') { return $str; } if ($pad_type !== (int) $pad_type) { if ($pad_type === 'left') { $pad_type = \STR_PAD_LEFT; } elseif ($pad_type === 'right') { $pad_type = \STR_PAD_RIGHT; } elseif ($pad_type === 'both') { $pad_type = \STR_PAD_BOTH; } else { throw new \InvalidArgumentException( 'Pad expects $pad_type to be "STR_PAD_*" or ' . "to be one of 'left', 'right' or 'both'" ); } } if ($encoding === 'UTF-8') { $str_length = (int) \mb_strlen($str); if ($pad_length >= $str_length) { switch ($pad_type) { case \STR_PAD_LEFT: $ps_length = (int) \mb_strlen($pad_string); $diff = ($pad_length - $str_length); $pre = (string) \mb_substr( \str_repeat($pad_string, (int) \ceil($diff / $ps_length)), 0, $diff ); $post = ''; break; case \STR_PAD_BOTH: $diff = ($pad_length - $str_length); $ps_length_left = (int) \floor($diff / 2); $ps_length_right = (int) \ceil($diff / 2); $pre = (string) \mb_substr( \str_repeat($pad_string, $ps_length_left), 0, $ps_length_left ); $post = (string) \mb_substr( \str_repeat($pad_string, $ps_length_right), 0, $ps_length_right ); break; case \STR_PAD_RIGHT: default: $ps_length = (int) \mb_strlen($pad_string); $diff = ($pad_length - $str_length); $post = (string) \mb_substr( \str_repeat($pad_string, (int) \ceil($diff / $ps_length)), 0, $diff ); $pre = ''; } return $pre . $str . $post; } return $str; } $encoding = self::normalize_encoding($encoding, 'UTF-8'); $str_length = (int) self::strlen($str, $encoding); if ($pad_length >= $str_length) { switch ($pad_type) { case \STR_PAD_LEFT: $ps_length = (int) self::strlen($pad_string, $encoding); $diff = ($pad_length - $str_length); $pre = (string) self::substr( \str_repeat($pad_string, (int) \ceil($diff / $ps_length)), 0, $diff, $encoding ); $post = ''; break; case \STR_PAD_BOTH: $diff = ($pad_length - $str_length); $ps_length_left = (int) \floor($diff / 2); $ps_length_right = (int) \ceil($diff / 2); $pre = (string) self::substr( \str_repeat($pad_string, $ps_length_left), 0, $ps_length_left, $encoding ); $post = (string) self::substr( \str_repeat($pad_string, $ps_length_right), 0, $ps_length_right, $encoding ); break; case \STR_PAD_RIGHT: default: $ps_length = (int) self::strlen($pad_string, $encoding); $diff = ($pad_length - $str_length); $post = (string) self::substr( \str_repeat($pad_string, (int) \ceil($diff / $ps_length)), 0, $diff, $encoding ); $pre = ''; } return $pre . $str . $post; } return $str; } /** * Returns a new string of a given length such that both sides of the * string are padded. Alias for "UTF8::str_pad()" with a $pad_type of 'both'. * * @param string $str * @param int $lengthDesired string length after padding.
* @param string $pad_str [optional]String used to pad, defaults to space. Default: ' '
* @param string $encoding [optional]Set the charset for e.g. "mb_" function
* * @psalm-pure * * @return string *The string with padding applied.
*/ public static function str_pad_both( string $str, int $length, string $pad_str = ' ', string $encoding = 'UTF-8' ): string { return self::str_pad( $str, $length, $pad_str, \STR_PAD_BOTH, $encoding ); } /** * Returns a new string of a given length such that the beginning of the * string is padded. Alias for "UTF8::str_pad()" with a $pad_type of 'left'. * * @param string $str * @param int $lengthDesired string length after padding.
* @param string $pad_str [optional]String used to pad, defaults to space. Default: ' '
* @param string $encoding [optional]Set the charset for e.g. "mb_" function
* * @psalm-pure * * @return string *The string with left padding.
*/ public static function str_pad_left( string $str, int $length, string $pad_str = ' ', string $encoding = 'UTF-8' ): string { return self::str_pad( $str, $length, $pad_str, \STR_PAD_LEFT, $encoding ); } /** * Returns a new string of a given length such that the end of the string * is padded. Alias for "UTF8::str_pad()" with a $pad_type of 'right'. * * @param string $str * @param int $lengthDesired string length after padding.
* @param string $pad_str [optional]String used to pad, defaults to space. Default: ' '
* @param string $encoding [optional]Set the charset for e.g. "mb_" function
* * @psalm-pure * * @return string *The string with right padding.
*/ public static function str_pad_right( string $str, int $length, string $pad_str = ' ', string $encoding = 'UTF-8' ): string { return self::str_pad( $str, $length, $pad_str, \STR_PAD_RIGHT, $encoding ); } /** * Repeat a string. * * EXAMPLE:UTF8::str_repeat("°~\xf0\x90\x28\xbc", 2); // '°~ð(¼°~ð(¼'
*
* @param string $str * The string to be repeated. *
* @param int<1, max> $multiplier* Number of time the input string should be * repeated. *
** multiplier has to be greater than or equal to 0. * If the multiplier is set to 0, the function * will return an empty string. *
* * @psalm-pure * * @return string *The repeated string.
* * @template T as string * @phpstan-param T $str * @phpstan-return (T is non-empty-string ? non-empty-string : string) */ public static function str_repeat(string $str, int $multiplier): string { $str = self::filter($str); return \str_repeat($str, $multiplier); } /** * INFO: This is only a wrapper for "str_replace()" -> the original functions is already UTF-8 safe. * * Replace all occurrences of the search string with the replacement string * * @see http://php.net/manual/en/function.str-replace.php * * @param string|string[] $search* The value being searched for, otherwise known as the needle. * An array may be used to designate multiple needles. *
* @param string|string[] $replace* The replacement value that replaces found search * values. An array may be used to designate multiple replacements. *
* @param string|string[] $subject* The string or array of strings being searched and replaced on, * otherwise known as the haystack. *
** If subject is an array, then the search and * replace is performed with every entry of * subject, and the return value is an array as * well. *
* @param int|null $count [optional]* If passed, this will hold the number of matched and replaced needles. *
* * @psalm-pure * * @return string|string[] *This function returns a string or an array with the replaced values.
* * @template TStrReplaceSubject * @phpstan-param TStrReplaceSubject $subject * @phpstan-return TStrReplaceSubject * * @deprecated please use \str_replace() instead */ public static function str_replace( $search, $replace, $subject, ?int &$count = null ) { /** * @psalm-suppress PossiblyNullArgument * @phpstan-var TStrReplaceSubject $return; */ $return = \str_replace( $search, $replace, $subject, $count ); return $return; } /** * Replaces $search from the beginning of string with $replacement. * * @param string $strThe input string.
* @param string $searchThe string to search for.
* @param string $replacementThe replacement.
* * @psalm-pure * * @return string *A string after the replacements.
*/ public static function str_replace_beginning( string $str, string $search, string $replacement ): string { if ($str === '') { if ($replacement === '') { return ''; } if ($search === '') { return $replacement; } } if ($search === '') { return $str . $replacement; } $searchLength = \strlen($search); if (\strncmp($str, $search, $searchLength) === 0) { return $replacement . \substr($str, $searchLength); } return $str; } /** * Replaces $search from the ending of string with $replacement. * * @param string $strThe input string.
* @param string $searchThe string to search for.
* @param string $replacementThe replacement.
* * @psalm-pure * * @return string *A string after the replacements.
*/ public static function str_replace_ending( string $str, string $search, string $replacement ): string { if ($str === '') { if ($replacement === '') { return ''; } if ($search === '') { return $replacement; } } if ($search === '') { return $str . $replacement; } if (\strpos($str, $search, \strlen($str) - \strlen($search)) !== false) { $str = \substr($str, 0, -\strlen($search)) . $replacement; } return $str; } /** * Replace the first "$search"-term with the "$replace"-term. * * @param string $search * @param string $replace * @param string $subject * * @psalm-pure * * @return string * * @psalm-suppress InvalidReturnType */ public static function str_replace_first( string $search, string $replace, string $subject ): string { $pos = self::strpos($subject, $search); if ($pos !== false) { /** * @psalm-suppress InvalidReturnStatement */ return self::substr_replace( $subject, $replace, $pos, (int) self::strlen($search) ); } return $subject; } /** * Replace the last "$search"-term with the "$replace"-term. * * @param string $search * @param string $replace * @param string $subject * * @psalm-pure * * @return string * * @psalm-suppress InvalidReturnType */ public static function str_replace_last( string $search, string $replace, string $subject ): string { $pos = self::strrpos($subject, $search); if ($pos !== false) { /** * @psalm-suppress InvalidReturnStatement */ return self::substr_replace( $subject, $replace, $pos, (int) self::strlen($search) ); } return $subject; } /** * Shuffles all the characters in the string. * * INFO: uses random algorithm which is weak for cryptography purposes * * EXAMPLE:UTF8::str_shuffle('fòô bàř fòô'); // 'àòôřb ffòô '
*
* @param string $str The input string
* @param string $encoding [optional]Set the charset for e.g. "mb_" function
* * @return string *The shuffled string.
* * @template T as string * @phpstan-param T $str * @phpstan-return (T is non-empty-string ? non-empty-string : string) */ public static function str_shuffle(string $str, string $encoding = 'UTF-8'): string { if ($encoding === 'UTF-8') { $indexes = \range(0, (int) \mb_strlen($str) - 1); \shuffle($indexes); // init $shuffled_str = ''; foreach ($indexes as &$i) { $tmp_sub_str = \mb_substr($str, $i, 1); if ($tmp_sub_str !== false) { /* @phpstan-ignore-line | old polyfill will return false, or? */ $shuffled_str .= $tmp_sub_str; } } } else { $encoding = self::normalize_encoding($encoding, 'UTF-8'); $indexes = \range(0, (int) self::strlen($str, $encoding) - 1); \shuffle($indexes); // init $shuffled_str = ''; foreach ($indexes as &$i) { $tmp_sub_str = self::substr($str, $i, 1, $encoding); if ($tmp_sub_str !== false) { $shuffled_str .= $tmp_sub_str; } } } return $shuffled_str; } /** * Returns the substring beginning at $start, and up to, but not including * the index specified by $end. If $end is omitted, the function extracts * the remaining string. If $end is negative, it is computed from the end * of the string. * * @param string $str * @param int $startInitial index from which to begin extraction.
* @param int|null $end [optional]Index at which to end extraction. Default: null
* @param string $encoding [optional]Set the charset for e.g. "mb_" function
* * @psalm-pure * * @return false|string *The extracted substring.
If str is shorter than start * characters long, FALSE will be returned. */ public static function str_slice( string $str, int $start, ?int $end = null, string $encoding = 'UTF-8' ) { if ($encoding === 'UTF-8') { if ($end === null) { $length = (int) \mb_strlen($str); } elseif ($end >= 0 && $end <= $start) { return ''; } elseif ($end < 0) { $length = (int) \mb_strlen($str) + $end - $start; } else { $length = $end - $start; } return \mb_substr($str, $start, $length); } $encoding = self::normalize_encoding($encoding, 'UTF-8'); if ($end === null) { $length = (int) self::strlen($str, $encoding); } elseif ($end >= 0 && $end <= $start) { return ''; } elseif ($end < 0) { $length = (int) self::strlen($str, $encoding) + $end - $start; } else { $length = $end - $start; } return self::substr($str, $start, $length, $encoding); } /** * Convert a string to e.g.: "snake_case" * * @param string $str * @param string $encoding [optional]
Set the charset for e.g. "mb_" function
* * @psalm-pure * * @return string *A string in snake_case.
*/ public static function str_snakeize(string $str, string $encoding = 'UTF-8'): string { if ($str === '') { return ''; } $str = \str_replace( '-', '_', self::normalize_whitespace($str) ); if ($encoding !== 'UTF-8' && $encoding !== 'CP850') { $encoding = self::normalize_encoding($encoding, 'UTF-8'); } $str = (string) \preg_replace_callback( '/([\\p{N}|\\p{Lu}])/u', /** * @param string[] $matches * * @psalm-pure * * @return string */ static function (array $matches) use ($encoding): string { $match = $matches[1]; $match_int = (int) $match; if ((string) $match_int === $match) { return '_' . $match . '_'; } if ($encoding === 'UTF-8') { return '_' . \mb_strtolower($match); } return '_' . self::strtolower($match, $encoding); }, $str ); $str = (string) \preg_replace( [ '/\\s+/u', // convert spaces to "_" '/^\\s+|\\s+$/u', // trim leading & trailing spaces '/_+/', // remove double "_" ], [ '_', '', '_', ], $str ); return \trim(\trim($str, '_')); // trim leading & trailing "_" + whitespace } /** * Sort all characters according to code points. * * EXAMPLE:UTF8::str_sort(' -ABC-中文空白- '); // ' ---ABC中文白空'
*
* @param string $str A UTF-8 string.
* @param bool $uniqueSort unique. If true, repeated characters are ignored.
* @param bool $descIf true, will sort characters in reverse code point order.
* * @psalm-pure * * @return string *A string of sorted characters.
*/ public static function str_sort(string $str, bool $unique = false, bool $desc = false): string { /** @var int[] $array */ $array = self::codepoints($str); if ($unique) { $array = \array_flip(\array_flip($array)); } if ($desc) { \arsort($array); } else { \asort($array); } return self::string($array); } /** * Convert a string to an array of Unicode characters. * * EXAMPLE:
* UTF8::str_split_array(['中文空白', 'test'], 2); // [['中文', '空白'], ['te', 'st']]
*
*
* @param int[]|string[] $input The string[] or int[] to split into array.
* @param int<1, max> $length [optional]Max character length of each array * element.
* @param bool $clean_utf8 [optional]Remove non UTF-8 chars from the * string.
* @param bool $try_to_use_mb_functions [optional]Set to false, if you don't want to use * "mb_substr"
* * @psalm-pure * * @return listAn array containing chunks of the input.
*/ public static function str_split_array( array $input, int $length = 1, bool $clean_utf8 = false, bool $try_to_use_mb_functions = true ): array { foreach ($input as &$v) { $v = self::str_split( $v, $length, $clean_utf8, $try_to_use_mb_functions ); } /** @var listUTF8::str_split('中文空白'); // array('中', '文', '空', '白')
*
* @param int|string $str The string or int to split into array.
* @param int<1, max> $length [optional]Max character length of each array * element.
* @param bool $clean_utf8 [optional]Remove non UTF-8 chars from the * string.
* @param bool $try_to_use_mb_functions [optional]Set to false, if you don't want to use * "mb_substr"
* * @psalm-pure * * @return listAn array containing chunks of chars from the input.
*/ public static function str_split( $str, int $length = 1, bool $clean_utf8 = false, bool $try_to_use_mb_functions = true ): array { /* @phpstan-ignore-next-line | we do not trust the phpdoc check */ if ($length <= 0) { return []; } // this is only an old fallback /** @noinspection PhpSillyAssignmentInspection - hack for phpstan */ /** @var int|int[]|string|string[] $str */ $str = $str; if (\is_array($str)) { /** @psalm-suppress InvalidReturnStatement */ /** @phpstan-ignore-next-line - old code :/ */ return self::str_split_array( $str, $length, $clean_utf8, $try_to_use_mb_functions ); } // init $str = (string) $str; if ($str === '') { return []; } if ($clean_utf8) { $str = self::clean($str); } if ( $try_to_use_mb_functions && self::$SUPPORT['mbstring'] === true ) { if (\function_exists('mb_str_split')) { try { /** * @psalm-suppress ImpureFunctionCall - why? */ $return = \mb_str_split($str, $length); } catch (\Error $e) { // PHP >= 8.0 : mb_str_split() will now throw ValueError on error. Previously, mb_str_split() returned false instead. $return = false; } if ($return !== false) { return $return; } } $i_max = \mb_strlen($str); if ($i_max <= 127) { $ret = []; for ($i = 0; $i < $i_max; ++$i) { $ret[] = \mb_substr($str, $i, 1); } } else { $return_array = []; \preg_match_all('/./us', $str, $return_array); $ret = $return_array[0] ?? []; } } elseif (self::$SUPPORT['pcre_utf8'] === true) { $return_array = []; \preg_match_all('/./us', $str, $return_array); $ret = $return_array[0] ?? []; } else { // fallback $ret = []; $len = \strlen($str); for ($i = 0; $i < $len; ++$i) { if (($str[$i] & "\x80") === "\x00") { $ret[] = $str[$i]; } elseif ( isset($str[$i + 1]) && ($str[$i] & "\xE0") === "\xC0" ) { if (($str[$i + 1] & "\xC0") === "\x80") { $ret[] = $str[$i] . $str[$i + 1]; ++$i; } } elseif ( isset($str[$i + 2]) && ($str[$i] & "\xF0") === "\xE0" ) { if ( ($str[$i + 1] & "\xC0") === "\x80" && ($str[$i + 2] & "\xC0") === "\x80" ) { $ret[] = $str[$i] . $str[$i + 1] . $str[$i + 2]; $i += 2; } } elseif ( isset($str[$i + 3]) && ($str[$i] & "\xF8") === "\xF0" ) { if ( ($str[$i + 1] & "\xC0") === "\x80" && ($str[$i + 2] & "\xC0") === "\x80" && ($str[$i + 3] & "\xC0") === "\x80" ) { $ret[] = $str[$i] . $str[$i + 1] . $str[$i + 2] . $str[$i + 3]; $i += 3; } } } } if ($length > 1) { return \array_map( static function (array $item): string { /* @phpstan-ignore-next-line | "array_map + array_chunk" is not supported by phpstan?! */ return \implode('', $item); }, \array_chunk($ret, $length) ); } if (isset($ret[0]) && $ret[0] === '') { return []; } return $ret; } /** * Splits the string with the provided regular expression, returning an * array of strings. An optional integer $limit will truncate the * results. * * @param string $str * @param string $patternThe regex with which to split the string.
* @param int $limit [optional]Maximum number of results to return. Default: -1 === no limit
* * @psalm-pure * * @return string[] *An array of strings.
*/ public static function str_split_pattern(string $str, string $pattern, int $limit = -1): array { if ($limit === 0) { return []; } if ($pattern === '') { return [$str]; } if (self::$SUPPORT['mbstring'] === true) { if ($limit >= 0) { $result_tmp = \mb_split($pattern, $str); if ($result_tmp === false) { return []; } $result = []; foreach ($result_tmp as $item_tmp) { if ($limit === 0) { break; } --$limit; $result[] = $item_tmp; } return $result; } $result = \mb_split($pattern, $str); if ($result === false) { return []; } return $result; } if ($limit > 0) { ++$limit; } else { $limit = -1; } $array = \preg_split('/' . \preg_quote($pattern, '/') . '/u', $str, $limit); if ($array === false) { return []; } if ($limit > 0 && \count($array) === $limit) { \array_pop($array); } return $array; } /** * Check if the string starts with the given substring. * * EXAMPLE:
* UTF8::str_starts_with('ΚόσμεMiddleEnd', 'Κόσμε'); // true
* UTF8::str_starts_with('ΚόσμεMiddleEnd', 'κόσμε'); // false
*
*
* @param string $haystack The string to search in.
* @param string $needleThe substring to search for.
* * @psalm-pure * * @return bool */ public static function str_starts_with(string $haystack, string $needle): bool { if ($needle === '') { return true; } if ($haystack === '') { return false; } if (\PHP_VERSION_ID >= 80000) { /** @phpstan-ignore-next-line - only for PHP8 */ return \str_starts_with($haystack, $needle); } return \strncmp($haystack, $needle, \strlen($needle)) === 0; } /** * Returns true if the string begins with any of $substrings, false otherwise. * * - case-sensitive * * @param string $strThe input string.
* @param scalar[] $substringsSubstrings to look for.
* * @psalm-pure * * @return bool *Whether or not $str starts with $substring.
*/ public static function str_starts_with_any(string $str, array $substrings): bool { if ($str === '') { return false; } if ($substrings === []) { return false; } foreach ($substrings as &$substring) { if (self::str_starts_with($str, (string) $substring)) { return true; } } return false; } /** * Gets the substring after the first occurrence of a separator. * * @param string $strThe input string.
* @param string $separatorThe string separator.
* @param string $encoding [optional]Default: 'UTF-8'
* * @psalm-pure * * @return string */ public static function str_substr_after_first_separator(string $str, string $separator, string $encoding = 'UTF-8'): string { if ($separator === '' || $str === '') { return ''; } if ($encoding === 'UTF-8') { $offset = \mb_strpos($str, $separator); if ($offset === false) { return ''; } return (string) \mb_substr( $str, $offset + (int) \mb_strlen($separator) ); } $offset = self::strpos($str, $separator, 0, $encoding); if ($offset === false) { return ''; } return (string) \mb_substr( $str, $offset + (int) self::strlen($separator, $encoding), null, $encoding ); } /** * Gets the substring after the last occurrence of a separator. * * @param string $strThe input string.
* @param string $separatorThe string separator.
* @param string $encoding [optional]Default: 'UTF-8'
* * @psalm-pure * * @return string */ public static function str_substr_after_last_separator( string $str, string $separator, string $encoding = 'UTF-8' ): string { if ($separator === '' || $str === '') { return ''; } if ($encoding === 'UTF-8') { $offset = \mb_strrpos($str, $separator); if ($offset === false) { return ''; } return (string) \mb_substr( $str, $offset + (int) \mb_strlen($separator) ); } $offset = self::strrpos($str, $separator, 0, $encoding); if ($offset === false) { return ''; } return (string) self::substr( $str, $offset + (int) self::strlen($separator, $encoding), null, $encoding ); } /** * Gets the substring before the first occurrence of a separator. * * @param string $strThe input string.
* @param string $separatorThe string separator.
* @param string $encoding [optional]Default: 'UTF-8'
* * @psalm-pure * * @return string */ public static function str_substr_before_first_separator( string $str, string $separator, string $encoding = 'UTF-8' ): string { if ($separator === '' || $str === '') { return ''; } if ($encoding === 'UTF-8') { $offset = \mb_strpos($str, $separator); if ($offset === false) { return ''; } return (string) \mb_substr( $str, 0, $offset ); } $offset = self::strpos($str, $separator, 0, $encoding); if ($offset === false) { return ''; } return (string) self::substr( $str, 0, $offset, $encoding ); } /** * Gets the substring before the last occurrence of a separator. * * @param string $strThe input string.
* @param string $separatorThe string separator.
* @param string $encoding [optional]Default: 'UTF-8'
* * @psalm-pure * * @return string */ public static function str_substr_before_last_separator(string $str, string $separator, string $encoding = 'UTF-8'): string { if ($separator === '' || $str === '') { return ''; } if ($encoding === 'UTF-8') { $offset = \mb_strrpos($str, $separator); if ($offset === false) { return ''; } return (string) \mb_substr( $str, 0, $offset ); } $offset = self::strrpos($str, $separator, 0, $encoding); if ($offset === false) { return ''; } $encoding = self::normalize_encoding($encoding, 'UTF-8'); return (string) self::substr( $str, 0, $offset, $encoding ); } /** * Gets the substring after (or before via "$before_needle") the first occurrence of the "$needle". * * @param string $strThe input string.
* @param string $needleThe string to look for.
* @param bool $before_needle [optional]Default: false
* @param string $encoding [optional]Default: 'UTF-8'
* * @psalm-pure * * @return string */ public static function str_substr_first( string $str, string $needle, bool $before_needle = false, string $encoding = 'UTF-8' ): string { if ($str === '' || $needle === '') { return ''; } if ($encoding === 'UTF-8') { if ($before_needle) { $part = \mb_strstr( $str, $needle, $before_needle ); } else { $part = \mb_strstr( $str, $needle ); } } else { $part = self::strstr( $str, $needle, $before_needle, $encoding ); } return $part === false ? '' : $part; } /** * Gets the substring after (or before via "$before_needle") the last occurrence of the "$needle". * * @param string $strThe input string.
* @param string $needleThe string to look for.
* @param bool $before_needle [optional]Default: false
* @param string $encoding [optional]Default: 'UTF-8'
* * @psalm-pure * * @return string */ public static function str_substr_last( string $str, string $needle, bool $before_needle = false, string $encoding = 'UTF-8' ): string { if ($str === '' || $needle === '') { return ''; } if ($encoding === 'UTF-8') { if ($before_needle) { $part = \mb_strrchr( $str, $needle, $before_needle ); } else { $part = \mb_strrchr( $str, $needle ); } } else { $part = self::strrchr( $str, $needle, $before_needle, $encoding ); } return $part === false ? '' : $part; } /** * Surrounds $str with the given substring. * * @param string $str * @param string $substringThe substring to add to both sides.
* * @psalm-pure * * @return string *A string with the substring both prepended and appended.
* * @template T as string * @template TSub as string * @phpstan-param T $str * @phpstan-param TSub $substring * @phpstan-return (T is non-empty-string ? non-empty-string : (TSub is non-empty-string ? non-empty-string : string)) */ public static function str_surround(string $str, string $substring): string { return $substring . $str . $substring; } /** * Returns a trimmed string with the first letter of each word capitalized. * Also accepts an array, $ignore, allowing you to list words not to be * capitalized. * * @param string $str * @param string[]|null $ignore [optional]An array of words not to capitalize or * null. Default: null
* @param string $encoding [optional]Default: 'UTF-8'
* @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. ẞ -> ß
* @param bool $use_trim_first [optional]true === trim the input string, * first
* @param string|null $word_define_chars [optional]An string of chars that will be used as * whitespace separator === words.
* * @psalm-pure * * @return string *The titleized string.
*/ public static function str_titleize( string $str, ?array $ignore = null, string $encoding = 'UTF-8', bool $clean_utf8 = false, ?string $lang = null, bool $try_to_keep_the_string_length = false, bool $use_trim_first = true, ?string $word_define_chars = null ): string { if ($str === '') { return ''; } if ($encoding !== 'UTF-8' && $encoding !== 'CP850') { $encoding = self::normalize_encoding($encoding, 'UTF-8'); } if ($use_trim_first) { $str = \trim($str); } if ($clean_utf8) { $str = self::clean($str); } $use_mb_functions = $lang === null && !$try_to_keep_the_string_length; if ($word_define_chars) { $word_define_chars = \preg_quote($word_define_chars, '/'); } else { $word_define_chars = ''; } $str = (string) \preg_replace_callback( '/([^\\s' . $word_define_chars . ']+)/u', static function (array $match) use ($try_to_keep_the_string_length, $lang, $ignore, $use_mb_functions, $encoding): string { if ($ignore !== null && \in_array($match[0], $ignore, true)) { return $match[0]; } if ($use_mb_functions) { if ($encoding === 'UTF-8') { return \mb_strtoupper(\mb_substr($match[0], 0, 1)) . \mb_strtolower(\mb_substr($match[0], 1)); } return \mb_strtoupper(\mb_substr($match[0], 0, 1, $encoding), $encoding) . \mb_strtolower(\mb_substr($match[0], 1, null, $encoding), $encoding); } return self::ucfirst( self::strtolower( $match[0], $encoding, false, $lang, $try_to_keep_the_string_length ), $encoding, false, $lang, $try_to_keep_the_string_length ); }, $str ); return $str; } /** * Convert a string into a obfuscate string. * * EXAMPLE:
*
* UTF8::str_obfuscate('lars@moelleken.org', 0.5, '*', ['@', '.']); // e.g. "l***@m**lleke*.*r*"
*
*
* @param string $str
* @param float $percent
* @param string $obfuscateChar
* @param string[] $keepChars
*
* @psalm-pure
*
* @return string
* The obfuscate string.
*/ public static function str_obfuscate( string $str, float $percent = 0.5, string $obfuscateChar = '*', array $keepChars = [] ): string { $obfuscateCharHelper = "\u{2603}"; $str = \str_replace($obfuscateChar, $obfuscateCharHelper, $str); $chars = self::chars($str); $charsMax = \count($chars); $charsMaxChange = \round($charsMax * $percent); $charsCounter = 0; $charKeyDone = []; while ($charsCounter < $charsMaxChange) { foreach ($chars as $charKey => $char) { if (isset($charKeyDone[$charKey])) { continue; } if (\random_int(0, 100) > 50) { continue; } if ($char === $obfuscateChar) { continue; } ++$charsCounter; $charKeyDone[$charKey] = true; if ($charsCounter > $charsMaxChange) { break; } if (\in_array($char, $keepChars, true)) { continue; } $chars[$charKey] = $obfuscateChar; } } $str = \implode('', $chars); return \str_replace($obfuscateCharHelper, $obfuscateChar, $str); } /** * Returns a trimmed string in proper title case. * * Also accepts an array, $ignore, allowing you to list words not to be * capitalized. * * Adapted from John Gruber's script. * * @see https://gist.github.com/gruber/9f9e8650d68b13ce4d78 * * @param string $str * @param string[] $ignoreAn array of words not to capitalize.
* @param string $encoding [optional]Set the charset for e.g. "mb_" function
* * @psalm-pure * * @return string *The titleized string.
*/ public static function str_titleize_for_humans( string $str, array $ignore = [], string $encoding = 'UTF-8' ): string { if ($str === '') { return ''; } $small_words = [ '(?