Validateurs de valeurs

Avez-vous besoin de vérifier rapidement et simplement que dans une variable se trouve, par exemple, une adresse e-mail valide ? Cela vous sera utile avec Nette\Utils\Validators, une classe statique avec des fonctions utiles pour la validation de valeurs.

Installation :

composer require nette/utils

Tous les exemples supposent qu'un alias a été créé :

use Nette\Utils\Validators;

Utilisation de base

La classe dispose de nombreuses méthodes pour le contrôle des valeurs, comme par exemple isList(), isUnicode(), isEmail(), isUrl() etc. pour utilisation dans votre code :

if (!Validators::isEmail($email)) {
	throw new InvalidArgumentException;
}

De plus, elle sait vérifier si la valeur est l'un des types attendus, qui est une chaîne où les différentes options sont séparées par une barre verticale |. Nous pouvons ainsi facilement vérifier plusieurs types en utilisant is() :

if (!Validators::is($val, 'int|string|bool')) {
	// ...
}

Mais cela nous donne aussi la possibilité de créer un système où il est nécessaire d'écrire les attentes comme des chaînes (par exemple dans les annotations ou la configuration) et ensuite selon elles vérifier les valeurs.

Aux types attendus, on peut aussi ajouter une exigence assert(), qui, si elle n'est pas satisfaite, alors une exception est lancée.

Types attendus

Les types attendus forment une chaîne composée d'une ou plusieurs variantes séparées par une barre verticale |, similaire à la façon dont les types sont écrits en PHP (par ex. 'int|string|bool'). La notation nullable ?int est également acceptée.

Un tableau où tous les éléments sont d'un certain type s'écrit sous la forme int[].

Après certains types peut suivre un deux-points et la longueur :length ou une plage :[min]..[max], par ex. string:10 (chaîne de 10 octets de long), float:10.. (nombre 10 et plus), array:..10 (tableau jusqu'à dix éléments) ou list:10..20 (liste avec 10 à 20 éléments), ou éventuellement une expression régulière pour pattern:[0-9]+.

Aperçu des types et des règles :

Types PHP
array peut spécifier une plage pour le nombre d'éléments
bool  
float peut spécifier une plage pour la valeur
int peut spécifier une plage pour la valeur
null  
object  
resource  
scalar int|float|bool|string
string peut spécifier une plage pour la longueur en octets
callable  
iterable  
mixed  
pseudo-types
list tableau indexé, peut spécifier une plage pour le nombre d'éléments
none valeur vide : '', null, false
number int|float
numeric nombre y compris représentation textuelle
numericint entier y compris représentation textuelle
unicode chaîne UTF-8, peut spécifier une plage pour la longueur en caractères
classe de caractères (ne doit pas être une chaîne vide)
alnum tous les caractères sont alphanumériques
alpha tous les caractères sont des lettres [A-Za-z]
digit tous les caractères sont des chiffres
lower tous les caractères sont des lettres minuscules [a-z]
space tous les caractères sont des espaces
upper tous les caractères sont des lettres majuscules [A-Z]
xdigit tous les caractères sont des chiffres hexadécimaux [0-9A-Fa-f]
vérification de syntaxe
pattern expression régulière à laquelle doit correspondre la chaîne entière
email E-mail
identifier Identifiant PHP
url URL
uri URI
vérification d'environnement
class est une classe existante
interface est une interface existante
directory est un répertoire existant
file est un fichier existant

Assertions

assert ($value, string $expected, string $label='variable')void

Vérifie que la valeur est l'un des types attendus séparés par une barre verticale. Sinon, lance une exception Nette\Utils\AssertionException. Le mot variable dans le texte de l'exception peut être remplacé par un autre avec le paramètre $label.

Validators::assert('Nette', 'string:5'); // OK
Validators::assert('Lorem ipsum dolor sit', 'string:78');
// AssertionException: The variable expects to be string:78, string 'Lorem ipsum dolor sit' given.

assertField (array $array, string|int $key, ?string $expected=null, ?string $label=null)void

Vérifie si l'élément sous la clé $key dans le tableau $array est l'un des types attendus séparés par une barre verticale. Sinon, lance une exception Nette\Utils\AssertionException. La chaîne item '%' in array dans le texte de l'exception peut être remplacée par une autre avec le paramètre $label.

$arr = ['foo' => 'Nette'];

Validators::assertField($arr, 'foo', 'string:5'); // OK
Validators::assertField($arr, 'bar', 'string:15');
// AssertionException: Missing item 'bar' in array.
Validators::assertField($arr, 'foo', 'int');
// AssertionException: The item 'foo' in array expects to be int, string 'Nette' given.

Validateurs

is ($value, string $expected)bool

Vérifie si la valeur est l'un des types attendus séparés par une barre verticale.

Validators::is(1, 'int|float');  // true
Validators::is(23, 'int:0..10'); // false
Validators::is('Nette Framework', 'string:15');     // true, la longueur est de 15 octets
Validators::is('Nette Framework', 'string:8..');    // true
Validators::is('Nette Framework', 'string:30..40'); // false

isEmail (mixed $value): bool

Vérifie si la valeur est une adresse e-mail valide. Ne vérifie pas si le domaine existe réellement, vérifie seulement la syntaxe. La fonction prend également en compte les futurs TLD, qui peuvent être aussi en unicode.

Validators::isEmail('example@nette.org'); // true
Validators::isEmail('example@localhost'); // false
Validators::isEmail('nette');             // false

isInRange (mixed $value, array $range)bool

Vérifie si la valeur est dans la plage donnée [min, max], où la limite supérieure ou inférieure peut être omise (null). Peut comparer des nombres, des chaînes et des objets DateTime.

Si les deux limites manquent ([null, null]) ou si la valeur est null, retourne false.

Validators::isInRange(5, [0, 5]);     // true
Validators::isInRange(23, [null, 5]); // false
Validators::isInRange(23, [5]);       // true
Validators::isInRange(1, [5]);        // false

isNone (mixed $value): bool

Vérifie si la valeur est 0, '', false ou null.

Validators::isNone(0); // true
Validators::isNone(''); // true
Validators::isNone(false); // true
Validators::isNone(null); // true
Validators::isNone('nette'); // false

isNumeric (mixed $value)bool

Vérifie si la valeur est un nombre ou un nombre écrit dans une chaîne.

Validators::isNumeric(23);      // true
Validators::isNumeric(1.78);    // true
Validators::isNumeric('+42');   // true
Validators::isNumeric('3.14');  // true
Validators::isNumeric('nette'); // false
Validators::isNumeric('1e6');   // false

isNumericInt (mixed $value)bool

Vérifie si la valeur est un entier ou un nombre écrit dans une chaîne.

Validators::isNumericInt(23);      // true
Validators::isNumericInt(1.78);    // false
Validators::isNumericInt('+42');   // true
Validators::isNumericInt('3.14');  // false
Validators::isNumericInt('nette'); // false

isPhpIdentifier (string $value)bool

Vérifie si la valeur est un identifiant syntaxiquement valide en PHP, par exemple pour les noms de classes, méthodes, fonctions, etc.

Validators::isPhpIdentifier('');        // false
Validators::isPhpIdentifier('Hello1');  // true
Validators::isPhpIdentifier('1Hello');  // false
Validators::isPhpIdentifier('one two'); // false

isBuiltinType (string $type)bool

Détermine si $type est un type intégré de PHP. Sinon, c'est un nom de classe.

Validators::isBuiltinType('string'); // true
Validators::isBuiltinType('Foo');    // false

isTypeDeclaration (string $type)bool

Vérifie si la déclaration de type donnée est syntaxiquement valide.

Validators::isTypeDeclaration('?string');      // true
Validators::isTypeDeclaration('string|null');  // true
Validators::isTypeDeclaration('Foo&Bar');      // true
Validators::isTypeDeclaration('(A&C)|null');   // true

Validators::isTypeDeclaration('?string|null'); // false
Validators::isTypeDeclaration('|foo');         // false
Validators::isTypeDeclaration('(A|B)');        // false

isClassKeyword (string $type)bool

Détermine si $type est l'un des types internes self, parent, static.

Validators::isClassKeyword('self'); // true
Validators::isClassKeyword('Foo');  // false

isUnicode (mixed $value)bool

Vérifie si la valeur est une chaîne UTF-8 valide.

Validators::isUnicode('nette'); // true
Validators::isUnicode('');      // true
Validators::isUnicode("\xA0");  // false

isUrl (mixed $value): bool

Vérifie si la valeur est une adresse URL valide.

Validators::isUrl('https://nette.org:8080/path?query#fragment'); // true
Validators::isUrl('http://localhost');            // true
Validators::isUrl('http://192.168.1.1');          // true
Validators::isUrl('http://[::1]');                // true
Validators::isUrl('http://user:pass@nette.org');  // false
Validators::isUrl('nette.org');                   // false

isUri (string $value): bool

Vérifie si la valeur est une adresse URI valide, c'est-à-dire en fait une chaîne commençant par un schéma syntaxiquement valide.

Validators::isUri('https://nette.org');           // true
Validators::isUri('mailto:gandalf@example.org');  // true
Validators::isUri('nette.org');                   // false
version: 4.0