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.

normalizeNewLines (string $s): string

Standardize line endings to unix-like.

$unixLikeLines = Strings::normalizeNewLines($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

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

Checks if $haystack string end with $needle.

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

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

Checks if $haystack string contains $needle.

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

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);

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); // '©'

Regular Expressions

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

split (string $subject, string $pattern, int $flags=null): 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 $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']

match (string $subject, string $pattern, int $flags=null, int $offset=0): ?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

The $flag can be set to the same flags as the preg_match function.

The $offset parameter can be used to specify the position to start the search from (in bytes).

matchAll (string $subject, string $pattern, int $flags=null, int $offset=0): array

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!!', '!!'],
] */

The $flag can be set to the same flags as the preg_match_all function, except that the PREG_SET_ORDER flag is the default value.