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

lower(string $s): string

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

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

upper(string $s): string

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

echo 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.

echo 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.

echo 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.

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

Editing a String

normalize(string $s): string

Removes right-side spaces, control sequences and unifies line endings to \n.

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

Adjusts a UTF-8 string for usage in URL, i.e. removes all accents and replaces all remaining characters except English alphabet letters and numerals with hyphens.

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

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

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

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

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

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.

echo 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?';
echo Strings::truncate($text, 5); // 'Hell…'
echo Strings::truncate($text, 20); // 'Hello, how are you…'
echo Strings::truncate($text, 30); // 'Hello, how are you today?'
echo 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).

echo Strings::indent('Nette'); // '	Nette'
echo 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.

echo Strings::padLeft('Nette', 6); // ' Nette'
echo Strings::padLeft('Nette', 8, '+'); // '+++Nette'
echo Strings::padLeft(' Nette', 11, 'WOW'); // 'WOWWO Nette'

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

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

echo Strings::padRight('Nette', 6); // 'Nette '
echo Strings::padRight('Nette', 8, '+'); // 'Nette+++'
echo Strings::padRight('Nette is ', 16, 'great'); // 'Nette is greatgr'

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

Returns a part of UTF-8 string.

echo Strings::substring('Nette is great', 0, 5); // 'Nette'
echo Strings::substring('Nette is great', 6, 2); // 'is'
echo Strings::substring('Nette is great', 9); // 'great'

normalizeNewLines(string $s): string

Standardize line endings to unix-like.

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

reverse(string $s): string

Reverse UTF-8 string.

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

length(string $s): int

Returns a length of a UTF-8 string.

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

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

Returns true if $haystack string begins with $needle.

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

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

Returns true if $haystack string end with $needle.

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

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

Returns true if $haystack string contains $needle.

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

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

Compares two UTF-8 strings or their parts, without taking character case into account. If $len is greater then zero, the respective amount of characters from the beginning of strings is compared, if it's negative, the respective amount of characters from the end is compared, if it's equal to zero, whole strings are compared.

echo Strings::compare('Nette', 'nette'); // true
echo Strings::compare('Nette', 'next', 2); // true - two first characters match
echo 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.

echo Strings::findPrefix('prefix-Nette', 'prefix-is', 'prefix-great'); // 'prefix-'
echo Strings::findPrefix(['prefix-Nette', 'prefix-is', 'prefix-great']); // 'prefix-'
echo 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.

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

Version 2 returns false instead of 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.

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

Version 2 returns false instead of null.

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

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

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

Version 2 returns false instead of 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 for UTF-8 encoding.

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

toAscii(string $s): string

Converts string to ASCII.

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

chr(int $code): string

Returns a specific character in UTF-8.

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

Regular Expressions

Class Strings contains a few methods for working with regular expressions. Unlike native php functions, it provides readable API and throws Nette\RegexpException if any regexp error occurs.

split(string $subject, string $pattern, int $flags=null): array

Splits a string into array by the regular expression. Argument $flag takes same arguments as preg_split, but PREG_SPLIT_DELIM_CAPTURE is set by default.

$res = Strings::split('One,  two,three', '~,\s*~');
// ['One', 'two', 'three']
$res = Strings::split('One,  two,three', '~(,)\s*~');
// ['One', ',', 'two', ',', 'three']

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

Checks if given string matches a regex pattern and returns an array with first found match and each subpattern. Argument $flag takes same arguments as function preg_match.

list($res) = Strings::match('One,  two,three', '~[a-z]+~i'); // 'One'
list($res) = Strings::match('One,  two,three', '~\d+~'); // null

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

Finds all occurrences matching regular expression pattern and returns a two-dimensional array. Argument $flag takes same arguments as function preg_match_all, but PREG_SET_ORDER is set by default.

$res = Strings::matchAll('One,  two,tree', '~[a-z]+~i');
/*
[
	0 => ['One'],
	1 => ['two'],
	2 => ['three'],
]
*/

$res = Strings::matchAll('One,  two,three', '~\d+~'); // []

replace(string $subject, string $pattern, string $replacement=null, int $limit=-1): string

Replaces all occurrences matching regular expression, passed in as second argument. Though it might as well be a hash-map in pattern => replacement format. The third argument is a replacement string or a callback and the fourth limits the count of replacements.

echo Strings::replace('One, two,three', '~[a-z]+~i', '*');
// '*,  *,*'

echo Strings::replace('One,  two,three', [
	'~[a-z]+~i' => '*',
	'~\s+~' => '+',
]);
// '*,+*,*'

echo Strings::replace('One,  two,three', '~[a-z]+~i', function (array $m): string {
	return strrev($m[0]);
});
// 'enO,  owt,eerht'