Fonctions des chaînes de caractères

Nette\Utils\Strings est une classe statique qui contient de nombreuses fonctions utiles pour travailler avec des chaînes de caractères codées UTF-8.

Installation :

composer require nette/utils

Tous les exemples supposent que l'alias de classe suivant est défini :

use Nette\Utils\Strings;

Letter Case

Ces fonctions nécessitent l'extension PHP mbstring.

lower(string $s): string

Convertit tous les caractères de la chaîne UTF-8 en minuscules.

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

upper(string $s): string

Convertit tous les caractères d'une chaîne UTF-8 en majuscules.

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

firstUpper(string $s): string

Convertit le premier caractère d'une chaîne UTF-8 en majuscule et laisse les autres caractères inchangés.

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

firstLower(string $s): string

Convertit le premier caractère d'une chaîne UTF-8 en minuscule et laisse les autres caractères inchangés.

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

capitalize(string $s): string

Convertit le premier caractère de chaque mot d'une chaîne UTF-8 en majuscule et les autres en minuscule.

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

Modification d'une chaîne de caractères

normalize(string $s): string

Supprime les caractères de contrôle, normalise les sauts de ligne à \n, supprime les lignes vides de début et de fin, coupe les espaces de fin de ligne, normalise UTF-8 à la forme normale de NFC.

unixNewLines(string $s): string

Convertit les sauts de ligne en \n utilisés sur les systèmes Unix. Les sauts de ligne sont : \n, \r, \r\n, U+2028 séparateur de ligne, U+2029 séparateur de paragraphe.

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

platformNewLines(string $s): string

Convertit les sauts de ligne en caractères spécifiques à la plate-forme actuelle, c'est-à-dire \r\n sous Windows et \n ailleurs. Les sauts de ligne sont \n, \r, \r\n, U+2028 séparateur de ligne, U+2029 séparateur de paragraphe.

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

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

Modifie la chaîne UTF-8 à la forme utilisée dans l'URL, c'est-à-dire supprime les diacritiques et remplace tous les caractères sauf les lettres de l'alphabet anglais et les chiffres par un trait d'union.

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

D'autres caractères peuvent également être préservés, mais ils doivent être passés en second argument.

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

Le troisième argument peut supprimer la conversion de la chaîne en minuscules.

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

Nécessite l'extension PHP intl.

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

Supprime tous les espaces à gauche et à droite (ou les caractères passés en second argument) d'une chaîne de caractères encodée en UTF-8.

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

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

Tronque une chaîne UTF-8 à une longueur maximale donnée, tout en essayant de ne pas couper des mots entiers. Seulement si la chaîne est tronquée, une ellipse (ou autre chose définie avec le troisième argument) est ajoutée à la chaîne.

$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

Indente un texte multiligne à partir de la gauche. Le deuxième argument définit le nombre de caractères d'indentation à utiliser, tandis que l'indentation elle-même est le troisième argument (tab par défaut).

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

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

Remplit une chaîne UTF-8 à une longueur donnée en ajoutant la chaîne $pad au début.

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

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

Ajoute une chaîne UTF-8 à une longueur donnée en ajoutant la chaîne $pad à la fin.

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

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

Renvoie une partie de la chaîne UTF-8 spécifiée par la position de départ $start et la longueur $length. Si $start est négatif, la chaîne retournée commencera au $start'ème caractère à partir de la fin de la chaîne.

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

reverse(string $s): string

Inverse la chaîne UTF-8.

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

length(string $s): int

Renvoie le nombre de caractères (et non d'octets) dans une chaîne UTF-8.

Il s'agit du nombre de points de code Unicode, qui peut différer du nombre de graphèmes.

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

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

Vérifie si la chaîne $haystack commence par $needle.

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

Utilise les natifs str_starts_with().

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

Vérifie si la chaîne $haystack se termine par $needle.

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

Utilisation de str_ends_with().

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

Vérifie si la chaîne $haystack contient $needle.

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

Utilise le natif str_contains().

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

Compare deux chaînes de caractères UTF-8 ou leurs parties, sans tenir compte de la casse des caractères. Si $length est nul, les chaînes entières sont comparées, s'il est négatif, le nombre correspondant de caractères depuis la fin des chaînes est comparé, sinon le nombre approprié de caractères depuis le début est comparé.

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

Trouve le préfixe commun des chaînes de caractères ou renvoie une chaîne vide si le préfixe n'a pas été trouvé.

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

Renvoie la partie de $haystack avant l'occurrence de $nth de $needle ou renvoie null si l'aiguille n'a pas été trouvée. Une valeur négative signifie que la recherche se fait à partir de la fin.

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

Renvoie une partie de $haystack après l'occurrence de $nth sur $needle ou renvoie null si $needle n'a pas été trouvé. Une valeur négative de $nth signifie que la recherche se fait à partir de la fin.

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

Renvoie la position en caractères de $nth, l'occurrence de $needle dans $haystack ou null si $needle n'a pas été trouvé. Une valeur négative de $nth signifie que la recherche se fait à partir de la fin.

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

Encodage

fixEncoding(string $s): string

Supprime tous les caractères UTF-8 invalides d'une chaîne de caractères.

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

checkEncoding(string $s): bool

Vérifie si la chaîne est valide dans l'encodage UTF-8.

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

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

toAscii(string $s): string

Convertit une chaîne UTF-8 en ASCII, c'est-à-dire qu'elle supprime les diacritiques, etc.

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

Nécessite l'extension PHP intl.

chr(int $code): string

Renvoie un caractère spécifique en UTF-8 à partir du point de code (numéro dans la plage 0×0000..D7FF ou 0×E000..10FFFF).

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

ord(string $char): int

Renvoie le point de code d'un caractère spécifique en UTF-8 (nombre compris entre 0×0000..D7FF ou 0×E000..10FFFF).

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

Expressions régulières

La classe Strings fournit des fonctions pour travailler avec des expressions régulières. Contrairement aux fonctions natives de PHP, elles disposent d'une API plus compréhensible, d'un meilleur support de l'Unicode et, surtout, d'une détection des erreurs. Toute erreur de compilation ou de traitement d'expression entraînera une exception Nette\RegexpException.

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

Divise la chaîne de caractères en tableaux selon l'expression régulière. Les expressions entre parenthèses seront également capturées et renvoyées.

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

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

Si $skipEmpty est true, seuls les éléments non vides seront renvoyés :

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

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

Si $limit est spécifié, seules les sous-chaînes jusqu'à la limite seront retournées et le reste de la chaîne sera placé dans le dernier élément. Une limite de –1 ou 0 signifie qu'il n'y a pas de limite.

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

Si $utf8 est true, l'évaluation passe en mode Unicode. Ceci est similaire à la spécification du modificateur u.

Si $captureOffset est true, pour chaque correspondance, sa position dans la chaîne sera également retournée (en octets ; en caractères si $utf8 est défini). Cela change la valeur de retour en un tableau où chaque élément est une paire composée de la chaîne de caractères correspondante et de sa 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

Recherche dans la chaîne la partie correspondant à l'expression régulière et renvoie un tableau contenant l'expression trouvée et les sous-expressions individuelles, ou null.

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

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

Si $unmatchedAsNull est true, les sous-motifs non appariés sont renvoyés comme nuls ; sinon, ils sont renvoyés comme une chaîne vide ou ne sont pas renvoyés :

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

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

Si $utf8 est true, l'évaluation passe en mode Unicode. Ceci est similaire à la spécification du modificateur u :

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

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

Le paramètre $offset peut être utilisé pour spécifier la position à partir de laquelle commencer la recherche (en octets ; en caractères si $utf8 est défini).

Si $captureOffset est true, pour chaque correspondance, sa position dans la chaîne sera également renvoyée (en octets ; en caractères si $utf8 est défini). Cela transforme la valeur de retour en un tableau où chaque élément est une paire constituée de la chaîne de caractères correspondante et de son décalage :

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): array

Recherche dans la chaîne toutes les occurrences correspondant à l'expression régulière et renvoie un tableau de tableaux contenant l'expression trouvée et chaque sous-expression.

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

Si $patternOrder est true, la structure des résultats change de sorte que le premier élément est un tableau de correspondances de motifs complets, le second est un tableau de chaînes correspondant au premier sous-modèle entre parenthèses, et ainsi de suite :

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

Si $unmatchedAsNull est true, les sous-motifs non appariés sont renvoyés sous la forme de null ; sinon, ils sont renvoyés sous la forme d'une chaîne vide ou ne sont pas renvoyés :

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

Si $utf8 est true, l'évaluation passe en mode Unicode. Ceci est similaire à la spécification du modificateur u :

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

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

Le paramètre $offset peut être utilisé pour spécifier la position à partir de laquelle commencer la recherche (en octets ; en caractères si $utf8 est défini).

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

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

Remplace toutes les occurrences correspondant à l'expression régulière. L'adresse $replacement est soit un masque de chaîne de remplacement, soit une fonction de rappel.

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

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

La fonction permet également des remplacements multiples en passant un tableau de la forme pattern => replacement dans le second paramètre :

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

Le paramètre $limit limite le nombre de substitutions. Limite –1 signifie aucune limite.

Si $utf8 est true, l'évaluation passe en mode Unicode. Ceci est similaire à la spécification du modificateur u.

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

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

Si $captureOffset est true, pour chaque correspondance, sa position dans la chaîne (en octets ; en caractères si $utf8 est défini) est également transmise à la fonction de rappel. Cela change la forme du tableau passé, où chaque élément est une paire composée de la chaîne de caractères correspondante et de sa 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]]

Si $unmatchedAsNull est true, les sous-motifs non appariés sont transmis à la fonction d'appel comme nuls ; sinon, ils sont transmis comme une chaîne vide ou ne sont pas transmis :

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']

Fonctions des chaînes de caractères

Letter Case

lower(string $s): string

upper(string $s): string

firstUpper(string $s): string

firstLower(string $s): string

capitalize(string $s): string

Modification d'une chaîne de caractères

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

Encodage

fixEncoding(string $s): string

checkEncoding(string $s): bool

toAscii(string $s): string

chr(int $code): string

ord(string $char): int

Expressions régulières

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): array

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