String Processing – Nette\Utils\Strings

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

All examples assume the following class alias is defined:

use Nette\Utils\Strings;

Letter case

lower($s)

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

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

upper($s)

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

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

firstUpper($s)

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

capitalize($s)

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($s)

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

webalize($s, $charlist=NULL, $lower=TRUE)

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($s, $charlist=NULL)

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($s, $maxLen, $append='…')

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($s, $level=1, $indentationChar="\t")

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($s, $length, $pad=' ')

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($s, $length, $pad=' ')

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'

fixEncoding($s)

Removes all invalid UTF-8 characters from a string.

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

bool checkEncoding($s)

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

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

int length($s)

Returns a length of a UTF-8 string.

echo Strings::length('Nette'); // '5'
echo Strings::length('červená'); // '7'

bool startsWith($haystack, $needle)

Returns TRUE if $haystack string begins with $needle.

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

bool endsWith($haystack, $needle)

Returns TRUE if $haystack string end with $needle.

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

bool contains($haystack, $needle)

Returns TRUE if $haystack string contains $needle.

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

bool compare($left, $right, $len=NULL)

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

chr($code)

Returns a specific character in UTF-8.

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

Generating a string

random($length=10, $charlist='0-9a-z')

Generates a random string of given length from characters specified in second argument. Supports intervals, such as 0-9 or A-Z.

echo Strings::random(); // '6zq3a1nl8n'
echo Strings::random(5, 'A-Z'); // 'HLKUR'

Regular expressions

Strings class 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.

array split($subject, $pattern, $flags=NULL)

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*~');
// array('One', 'two', 'three')
$res = Strings::split('One,  two,three', '~(,)\s*~');
// array('One', ',', 'two', ',', 'three')

array match($subject, $pattern, $flags=NULL, $offset=0)

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

array matchAll($subject, $pattern, $flags=NULL, $offset=0)

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');
/*
array(
	0 => array('One'),
	1 => array('two'),
	2 => array('three'),
)
*/

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

replace($subject, $pattern, $replacement=NULL, $limit=-1)

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', array(
	'~[a-z]+~i' => '*',
	'~\s+~' => '+',
));
// '*,+*,*'

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