Validateurs de valeurs

Vous avez besoin de vérifier rapidement et facilement qu'une variable contient par exemple une adresse électronique valide ? Alors Nette\Utils\Validators vous sera utile. Il s'agit d'une classe statique contenant des fonctions utiles pour la validation des valeurs.

Installation :

composer require nette/utils

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

use Nette\Utils\Validators;

Utilisation de base

La classe Validators possède un certain nombre de méthodes pour valider des valeurs, telles que isList(), isUnicode(), isEmail(), isUrl(), etc. à utiliser dans votre code :

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

En outre, il peut vérifier si la valeur satisfait à ce qu'on appelle les types attendus, qui est une chaîne de caractères où les différentes options sont séparées par une barre verticale |. Cela permet de vérifier facilement les types d'union en utilisant if():

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

Mais cela vous donne également la possibilité de créer un système où il est nécessaire d'écrire les attentes sous forme de chaînes (par exemple dans les annotations ou la configuration) et de vérifier ensuite en fonction de celles-ci.

Vous pouvez également déclarer une assertion, qui lève une exception si elle n'est pas satisfaite.

Types d'attentes

Un type attendu est une chaîne constituée d'une ou plusieurs variantes séparées par une barre verticale |, similar to writing types in PHP (ie. 'int|string|bool'). La notation nullable est également autorisée ?int.

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

Certains types peuvent être suivis d'un deux-points et de la longueur :length ou de l'intervalle :[min]..[max]par exemple string:10 (une chaîne de 10 octets), float:10.. (un nombre égal ou supérieur à 10), array:..10 (un tableau de 10 éléments maximum) ou list:10..20 (une liste de 10 à 20 éléments), ou encore une expression régulière comme pattern:[0-9]+.

Aperçu des types et des règles :

Assertion

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

Vérifie que la valeur est constituée des types attendus séparés par un pipe. Si ce n'est pas le cas, il lève l'exception Nette\Utils\AssertionException. Le mot variable dans le message d'exception peut être remplacé par 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 que l'élément $key dans le tableau $array est constitué des types attendus séparés par un pipe. Si ce n'est pas le cas, il lève l'exception Nette\Utils\AssertionException. La chaîne item '%' in array dans le message d'exception peut être remplacée par 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 constituée de types attendus séparés par un pipe.

Validators::is(1, 'int|float');  // true
Validators::is(23, 'int:0..10'); // false
Validators::is('Nette Framework', 'string:15');     // true, length is 15 bytes
Validators::is('Nette Framework', 'string:8..');    // true
Validators::is('Nette Framework', 'string:30..40'); // false

isEmail (mixed $value): bool

Vérifie que la valeur est une adresse électronique valide. Elle ne vérifie pas que le domaine existe réellement, seule la syntaxe est vérifiée. La fonction tient également compte des futurs TLD, qui peuvent également être 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 se situe dans l'intervalle donné [min, max]où la limite supérieure ou inférieure peut être omise (null). Les nombres, les chaînes de caractères et les objets DateTime peuvent être comparés.

Si les deux limites sont manquantes ([null, null]) ou si la valeur est null, il renvoie 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 nombre entier ou un nombre entier écrit dans une chaîne de caractères.

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, de méthodes, de 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é à PHP. Sinon, c'est le nom de la classe.

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

isTypeDeclaration (string $type): bool

Vérifie si la déclaration de type est syntaxiquement correcte.

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 que la valeur est une adresse URI valide, c'est-à-dire qu'il s'agit bien d'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