Validateurs de valeurs
**********************

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


Installation :

```shell
composer require nette/utils
```

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

```php
use Nette\Utils\Validators;
```


Utilisation de base .[#toc-basic-usage]
=======================================

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

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

En outre, il peut vérifier si la valeur satisfait à ce qu'on appelle les [types attendus |#expected types], 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()]:

```php
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 |#assert], qui lève une exception si elle n'est pas satisfaite.


Types d'attentes .[#toc-expected-types]
=======================================

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 :

.[wide]
| Types PHP ||
|--------------------------
| `array` .{width: 140px} | On peut donner une fourchette pour le nombre d'éléments
| `bool` |
| `float` - La valeur peut être indiquée dans une plage donnée.
| `int` - L'étendue de la valeur peut être donnée.
| `null` |
| `object` |
| `resource` |
| `scalar` | int\|float\|bool\|string
| `string` | La longueur en octets peut être indiquée dans une plage donnée.
| `callable` |
| `iterable` |
| `mixed` |
|------------------------------------------------
| pseudo-types ||
|------------------------------------------------
| `list` | [tableau indexé |#isList], le nombre d'éléments peut être donné dans une fourchette.
| `none` | valeur vide : `''`, `null`, `false`
| `number` | int\||float
| `numeric` | [nombre incluant une représentation textuelle |#isNumeric]
| `numericint`| [nombre entier incluant une représentation textuelle|#isNumericInt]
| `unicode` | [Chaîne de caractères UTF-8 |#isUnicode], la longueur en caractères peut être indiquée dans une fourchette
|------------------------------------------------
| classe de caractères (ne peut ê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]`
|------------------------------------------------
| validation de la syntaxe ||
|------------------------------------------------
| `pattern` | une expression régulière à laquelle la **entière** chaîne doit correspondre
| `email` | [Courriel |#isEmail]
| `identifier`| [Identifiant PHP |#isPhpIdentifier]
| `url` | [URL |#isUrl]
| `uri` | [URI |#isUri]
|------------------------------------------------
| Validation de l'environnement
|------------------------------------------------
| `class` | est une classe existante
| `interface` | est une interface existante
| `directory` | est un répertoire existant
| `file` | est un fichier existant


Assertion .[#toc-assertion]
===========================


assert($value, string $expected, string $label='variable'): void .[method]
--------------------------------------------------------------------------

Vérifie que la valeur est constituée des [types attendus |#expected types] séparés par un pipe. Si ce n'est pas le cas, il lève l'exception [api:Nette\Utils\AssertionException]. Le mot `variable` dans le message d'exception peut être remplacé par le paramètre `$label`.

```php
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 .[method]
-------------------------------------------------------------------------------------------------------

Vérifie que l'élément `$key` dans le tableau `$array` est constitué des [types attendus |#expected types] séparés par un pipe. Si ce n'est pas le cas, il lève l'exception [api:Nette\Utils\AssertionException]. La chaîne `item '%' in array` dans le message d'exception peut être remplacée par le paramètre `$label`.

```php
$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 .[#toc-validators]
==============================


is($value, string $expected): bool .[method]
--------------------------------------------

Vérifie si la valeur est constituée de [types attendus |#expected types] séparés par un pipe.

```php
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 .[method]
-------------------------------------

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 |https://en.wikipedia.org/wiki/Top-level_domain], qui peuvent également être en unicode.

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


isInRange(mixed $value, array $range): bool .[method]
-----------------------------------------------------

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

```php
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 .[method]
------------------------------------

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

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


isNumeric(mixed $value): bool .[method]
---------------------------------------

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

```php
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 .[method]
------------------------------------------

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

```php
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 .[method]
----------------------------------------------

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.

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


isBuiltinType(string $type): bool .[method]
-------------------------------------------

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

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


isTypeDeclaration(string $type): bool .[method]
-----------------------------------------------

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

```php
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 .[method]
--------------------------------------------

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

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


isUnicode(mixed $value): bool .[method]
---------------------------------------

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

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


isUrl(mixed $value): bool .[method]
-----------------------------------

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

```php
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 .[method]
------------------------------------

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.

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