String Functions

Nette\Utils\Strings is a static class, which contains many useful functions for working with UTF-8 encoded strings.

Installation:

composer require nette/utils

All examples assume the following class alias is defined:

use Nette\Utils\Strings;

Letter Case

These functions require the PHP extension mbstring.

lower (string $s): string

Converts all characters of UTF-8 string to lower case.

Strings::lower('Hello world'); // 'hello world'

upper (string $s): string

Converts all characters of a UTF-8 string to upper case.

Strings::upper('Hello world'); // 'HELLO WORLD'

firstUpper (string $s): string

Converts the first character of a UTF-8 string to upper case and leaves the other characters unchanged.

Strings::firstUpper('hello world'); // 'Hello world'

firstLower (string $s): string

Converts the first character of a UTF-8 string to lower case and leaves the other characters unchanged.

Strings::firstLower('Hello world'); // 'hello world'

capitalize (string $s): string

Converts the first character of every word of a UTF-8 string to upper case and the others to lower case.

Strings::capitalize('Hello world'); // 'Hello World'

Editing a String

normalize (string $s): string

Removes control characters, normalizes line breaks to \n, removes leading and trailing blank lines, trims end spaces on lines, normalizes UTF-8 to the normal form of NFC.

unixNewLines (string $s): string

Converts line breaks to \n used on Unix systems. The line breaks are: \n, \r, \r\n, U+2028 line separator, U+2029 paragraph separator.

$unixLikeLines = Strings::unixNewLines($string);

platformNewLines (string $s): string

Converts line breaks to characters specific to the current platform, i.e. \r\n on Windows and \n elsewhere. The line breaks are \n, \r, \r\n, U+2028 line separator, U+2029 paragraph separator.

$platformLines = Strings::platformNewLines($string);

webalize (string $s, ?string $charlist=null, bool $lower=true): string

Modifies the UTF-8 string to the form used in the URL, ie removes diacritics and replaces all characters except letters of the English alphabet and numbers with a hyphens.

Strings::webalize('žluťoučký kůň'); // 'zlutoucky-kun'

Other characters may be preserved as well, but they must be passed as second argument.

Strings::webalize('10. image_id', '._'); // '10.-image_id'

The third argument may suppress converting the string to lower case.

Strings::webalize('Hello world', null, false); // 'Hello-world'

Requires PHP extension intl.

trim (string $s, ?string $charlist=null): string

Removes all left and right side spaces (or the characters passed as second argument) from a UTF-8 encoded string.

Strings::trim('  Hello  '); // 'Hello'

truncate (string $s, int $maxLen, string $append=`'…'`): string

Truncates a UTF-8 string to given maximal length, while trying not to split whole words. Only if the string is truncated, an ellipsis (or something else set with third argument) is appended to the string.

$text = 'Hello, how are you today?';
Strings::truncate($text, 5);       // 'Hell…'
Strings::truncate($text, 20);      // 'Hello, how are you…'
Strings::truncate($text, 30);      // 'Hello, how are you today?'
Strings::truncate($text, 20, '~'); // 'Hello, how are you~'

indent (string $s, int $level=1, string $indentationChar=`"\t"`): string

Indents a multiline text from the left. Second argument sets how many indentation chars should be used, while the indent itself is the third argument (tab by default).

Strings::indent('Nette');         // "\tNette"
Strings::indent('Nette', 2, '+'); // '++Nette'

padLeft (string $s, int $length, string $pad=`' '`): string

Pads a UTF-8 string to given length by prepending the $pad string to the beginning.

Strings::padLeft('Nette', 6);        // ' Nette'
Strings::padLeft('Nette', 8, '+*');  // '+*+Nette'

padRight (string $s, int $length, string $pad=`' '`): string

Pads UTF-8 string to given length by appending the $pad string to the end.

Strings::padRight('Nette', 6);       // 'Nette '
Strings::padRight('Nette', 8, '+*'); // 'Nette+*+'

substring (string $s, int $start, ?int $length=null): string

Returns a part of UTF-8 string specified by starting position $start and length $length. If $start is negative, the returned string will start at the $start'th character from the end of string.

Strings::substring('Nette Framework', 0, 5); // 'Nette'
Strings::substring('Nette Framework', 6);    // 'Framework'
Strings::substring('Nette Framework', -4);   // 'work'

reverse (string $s): string

Reverses UTF-8 string.

Strings::reverse('Nette'); // 'etteN'

length (string $s): int

Returns number of characters (not bytes) in UTF-8 string.

That is the number of Unicode code points which may differ from the number of graphemes.

Strings::length('Nette'); // 5
Strings::length('red');   // 3

startsWith (string $haystack, string $needle): bool

Checks if $haystack string begins with $needle.

$haystack = 'Begins';
$needle = 'Be';
Strings::startsWith($haystack, $needle); // true

Use native str_starts_with().

endsWith (string $haystack, string $needle): bool

Checks if $haystack string end with $needle.

$haystack = 'Ends';
$needle = 'ds';
Strings::endsWith($haystack, $needle); // true

Use native str_ends_with().

contains (string $haystack, string $needle): bool

Checks if $haystack string contains $needle.

$haystack = 'Contains';
$needle = 'tai';
Strings::contains($haystack, $needle); // true

Use native str_contains().

compare (string $left, string $right, ?int $length=null): bool

Compares two UTF-8 strings or their parts, without taking character case into account. If $length is null, whole strings are compared, if it is negative, the corresponding number of characters from the end of the strings is compared, otherwise the appropriate number of characters from the beginning is compared.

Strings::compare('Nette', 'nette');     // true
Strings::compare('Nette', 'next', 2);   // true - two first characters match
Strings::compare('Nette', 'Latte', -2); // true - two last characters match

findPrefix (…$strings): string

Finds the common prefix of strings or returns empty string if the prefix was not found.

Strings::findPrefix('prefix-a', 'prefix-bb', 'prefix-c');   // 'prefix-'
Strings::findPrefix(['prefix-a', 'prefix-bb', 'prefix-c']); // 'prefix-'
Strings::findPrefix('Nette', 'is', 'great');                // ''

before (string $haystack, string $needle, int $nth=1): ?string

Returns part of $haystack before $nth occurence of $needle or returns null if the needle was not found. Negative value means searching from the end.

Strings::before('Nette_is_great', '_', 1);  // 'Nette'
Strings::before('Nette_is_great', '_', -2); // 'Nette'
Strings::before('Nette_is_great', ' ');     // null
Strings::before('Nette_is_great', '_', 3);  // null

after (string $haystack, string $needle, int $nth=1): ?string

Returns part of $haystack after $nth occurence of $needle or returns null if the $needle was not found. Negative value of $nth means searching from the end.

Strings::after('Nette_is_great', '_', 2);  // 'great'
Strings::after('Nette_is_great', '_', -1); // 'great'
Strings::after('Nette_is_great', ' ');     // null
Strings::after('Nette_is_great', '_', 3);  // null

indexOf (string $haystack, string $needle, int $nth=1): ?int

Returns position in characters of $nth occurence of $needle in $haystack or null if the $needle was not found. Negative value of $nth means searching from the end.

Strings::indexOf('abc abc abc', 'abc', 2);  // 4
Strings::indexOf('abc abc abc', 'abc', -1); // 8
Strings::indexOf('abc abc abc', 'd');       // null

Encoding

fixEncoding (string $s): string

Removes all invalid UTF-8 characters from a string.

$correctStrings = Strings::fixEncoding($string);

checkEncoding (string $s): bool

Checks if the string is valid in UTF-8 encoding.

$isUtf8 = Strings::checkEncoding($string);

Use Nette\Utils\Validator::isUnicode().

toAscii (string $s): string

Converts UTF-8 string to ASCII, ie removes diacritics etc.

Strings::toAscii('žluťoučký kůň'); // 'zlutoucky kun'

Requires PHP extension intl.

chr (int $code): string

Returns a specific character in UTF-8 from code point (number in range 0×0000..D7FF or 0xE000..10FFFF).

Strings::chr(0xA9); // '©'

ord (string $char): int

Returns a code point of specific character in UTF-8 (number in range 0×0000..D7FF or 0xE000..10FFFF).

Strings::ord('©'); // 0xA9

Regular Expressions

The Strings class provides functions for working with regular expressions. Unlike native PHP functions, they have a more understandable API, better Unicode support, and most importantly, error detection. Any compilation or expression processing error will throw a Nette\RegexpException exception.

split (string $subject, string $pattern, bool $captureOffset=false, bool $skipEmpty=false, int $limit=-1, bool $utf8=false): array

Divides the string into arrays according to the regular expression. Expressions in parentheses will be captured and returned as well.

Strings::split('hello, world', '~,\s*~');
// ['hello', 'world']

Strings::split('hello, world', '~(,)\s*~');
// ['hello', ',', 'world']``

If $skipEmpty is true, only non-empty items will be returned:

Strings::split('hello, world, ', '~,\s*~');
// ['hello', 'world', '']

Strings::split('hello, world, ', '~,\s*~', skipEmpty: true);
// ['hello', 'world']

If $limit is specified, only substrings up to the limit will be returned and the rest of the string will be placed in the last element. A limit of –1 or 0 means no limit.

Strings::split('hello, world, third', '~,\s*~', limit: 2);
// ['hello', 'world, third']

If $utf8 is true, the evaluation switches to Unicode mode. This is similar to specifying the u modifier.

If $captureOffset is true, for each occurring match, its position in the string will also be returned (in bytes; in characters if $utf8 is set). This changes the return value to an array where each element is a pair consisting of the matched string and its position.

Strings::split('žlutý, kůň', '~,\s*~', captureOffset: true);
// [['žlutý', 0], ['kůň', 9]]

Strings::split('žlutý, kůň', '~,\s*~', captureOffset: true, utf8: true);
// [['žlutý', 0], ['kůň', 7]]

match (string $subject, string $pattern, bool $captureOffset=false, int $offset=0, bool $unmatchedAsNull=false, bool $utf8=false): ?array

Searches the string for the part matching the regular expression and returns an array with the found expression and individual subexpressions, or null.

Strings::match('hello!', '~\w+(!+)~');
// ['hello!', '!']

Strings::match('hello!', '~X~');
// null

If $unmatchedAsNull is true, unmatched subpatterns are returned as null; otherwise they are returned as an empty string or not returned:

Strings::match('hello', '~\w+(!+)?~');
// ['hello']

Strings::match('hello', '~\w+(!+)?~', unmatchedAsNull: true);
// ['hello', null]

If $utf8 is true, the evaluation switches to Unicode mode. This is similar to specifying the u modifier:

Strings::match('žlutý kůň', '~\w+~');
// ['lut']

Strings::match('žlutý kůň', '~\w+~', utf8: true);
// ['žlutý']

The $offset parameter can be used to specify the position from which to start the search (in bytes; in characters if $utf8 is set).

Strings::match('žlutý!', '~\w+(!+)?~', captureOffset: true);
// [['lut', 2]]

Strings::match('žlutý!', '~\w+(!+)?~', captureOffset: true, utf8: true);
// [['žlutý!', 0], ['!', 5]]

matchAll (string $subject, string $pattern, bool $captureOffset=false, int $offset=0, bool $unmatchedAsNull=false, bool $patternOrder=false, bool $utf8=false, bool $lazy=false): array|Generator

Searches the string for all occurrences matching the regular expression and returns an array of arrays containing the found expression and each subexpression.

Strings::matchAll('hello, world!!', '~\w+(!+)?~');
/* [
	0 => ['hello'],
	1 => ['world!!', '!!'],
] */

If $patternOrder is true, the structure of the results changes so that the first item is an array of full pattern matches, the second is an array of strings corresponding to the first subpattern in parentheses, and so on:

Strings::matchAll('hello, world!!', '~\w+(!+)?~', patternOrder: true);
/* [
	0 => ['hello', 'world!!'],
	1 => ['', '!!'],
] */

If $unmatchedAsNull is true, unmatched subpatterns are returned as null; otherwise they are returned as an empty string or not returned:

Strings::matchAll('hello, world!!', '~\w+(!+)?~', unmatchedAsNull: true);
/* [
	0 => ['hello', null],
	1 => ['world!!', '!!'],
] */

If $utf8 is true, the evaluation switches to Unicode mode. This is similar to specifying the u modifier:

Strings::matchAll('žlutý kůň', '~\w+~');
/* [
	0 => ['lut'],
	1 => ['k'],
] */

Strings::matchAll('žlutý kůň', '~\w+~', utf8: true);
/* [
	0 => ['žlutý'],
	1 => ['kůň'],
] */

The $offset parameter can be used to specify the position from which to start the search (in bytes; in characters if $utf8 is set).

Strings::matchAll('žlutý kůň', '~\w+~', captureOffset: true);
/* [
	0 => [['lut', 2]],
	1 => [['k', 8]],
] */

Strings::matchAll('žlutý kůň', '~\w+~', captureOffset: true, utf8: true);
/* [
	0 => [['žlutý', 0]],
	1 => [['kůň', 6]],
] */

If $lazy is true, the function returns a Generator instead of an array, which provides significant performance benefits when working with large strings. The generator allows for matches to be found incrementally, rather than processing the entire string at once. This enables efficient handling of extremely large input texts. Additionally, you can interrupt processing at any time if you find the desired match, saving computational time.

$matches = Strings::matchAll($largeText, '~\w+~', lazy: true);
foreach ($matches as $match) {
    echo "Found: $match[0]\n";
    // Processing can be interrupted at any time
}

replace (string $subject, string|array $pattern, string|callable $replacement=`''`, int $limit=-1, bool $captureOffset=false, bool $unmatchedAsNull=false, bool $utf8=false): string

Replaces all occurrences matching the regular expression. The $replacement is either a replacement string mask or a callback.

Strings::replace('hello, world!', '~\w+~', '--');
// '--, --!'

Strings::replace('hello, world!', '~\w+~', fn($m) => strrev($m[0]));
// 'olleh, dlrow!'

The function also allows multiple replacements by passing an array of the form pattern => replacement in the second parameter:

Strings::replace('hello, world!', [
	'~\w+~' => '--',
	'~,\s+~' => ' ',
]);
// '-- --!'

The $limit parameter limits the number of substitutions. Limit –1 means no limit.

If $utf8 is true, the evaluation switches to Unicode mode. This is similar to specifying the u modifier.

Strings::replace('žlutý kůň', '~\w+~', '--');
// 'ž--ý --ůň'

Strings::replace('žlutý kůň', '~\w+~', '--', utf8: true);
// '-- --'

If $captureOffset is true, for each occurring match, its position in the string (in bytes; in characters if $utf8 is set) is also passed to the callback. This changes the form of the passed array, where each element is a pair consisting of the matched string and its position.

Strings::replace(
	'žlutý kůň',
	'~\w+~',
	function (array $m) { dump($m); return ''; },
	captureOffset: true,
);
// dumps [['lut', 2]] a [['k', 8]]

Strings::replace(
	'žlutý kůň',
	'~\w+~',
	function (array $m) { dump($m); return ''; },
	captureOffset: true,
	utf8: true,
);
// dumps [['žlutý', 0]] a [['kůň', 6]]

If $unmatchedAsNull is true, unmatched subpatterns are passed to the callback as null; otherwise they are passed as an empty string or not passed:

Strings::replace(
	'ac',
	'~(a)(b)*(c)~',
	function (array $m) { dump($m); return ''; },
);
// dumps ['ac', 'a', '', 'c']

Strings::replace(
	'ac',
	'~(a)(b)*(c)~',
	function (array $m) { dump($m); return ''; },
	unmatchedAsNull: true,
);
// dumps ['ac', 'a', null, 'c']

String Functions

Letter Case

lower (string $s): string

upper (string $s): string

firstUpper (string $s): string

firstLower (string $s): string

capitalize (string $s): string

Editing a String

normalize (string $s): string

unixNewLines (string $s): string

platformNewLines (string $s): string

webalize (string $s, ?string $charlist=null, bool $lower=true): string

trim (string $s, ?string $charlist=null): string

truncate (string $s, int $maxLen, string $append=`'…'`): string

indent (string $s, int $level=1, string $indentationChar=`"\t"`): string

padLeft (string $s, int $length, string $pad=`' '`): string

padRight (string $s, int $length, string $pad=`' '`): string

substring (string $s, int $start, ?int $length=null): string

reverse (string $s): string

length (string $s): int

startsWith (string $haystack, string $needle): bool

endsWith (string $haystack, string $needle): bool

contains (string $haystack, string $needle): bool

compare (string $left, string $right, ?int $length=null): bool

findPrefix (…$strings): string

before (string $haystack, string $needle, int $nth=1): ?string

after (string $haystack, string $needle, int $nth=1): ?string

indexOf (string $haystack, string $needle, int $nth=1): ?int

Encoding

fixEncoding (string $s): string

checkEncoding (string $s): bool

toAscii (string $s): string

chr (int $code): string

ord (string $char): int

Regular Expressions

split (string $subject, string $pattern, bool $captureOffset=false, bool $skipEmpty=false, int $limit=-1, bool $utf8=false): array

match (string $subject, string $pattern, bool $captureOffset=false, int $offset=0, bool $unmatchedAsNull=false, bool $utf8=false): ?array

matchAll (string $subject, string $pattern, bool $captureOffset=false, int $offset=0, bool $unmatchedAsNull=false, bool $patternOrder=false, bool $utf8=false, bool $lazy=false): array|Generator

replace (string $subject, string|array $pattern, string|callable $replacement='', int $limit=-1, bool $captureOffset=false, bool $unmatchedAsNull=false, bool $utf8=false): string

replace (string $subject, string|array $pattern, string|callable $replacement=`''`, int $limit=-1, bool $captureOffset=false, bool $unmatchedAsNull=false, bool $utf8=false): string