Validatori di valori
********************

.[perex]
Avete bisogno di verificare in modo rapido e semplice che una variabile contenga, per esempio, un indirizzo e-mail valido? Allora vi tornerà utile [api:Nette\Utils\Validators], una classe statica con utili funzioni per validare i valori.


Installazione:

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

Tutti gli esempi presuppongono che sia definito questo alias di classe:

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


Uso di base
===========

La classe `Validators` offre numerosi metodi per controllare i valori, come [#isUnicode()], [#isEmail()], [#isUrl()] e così via, da usare nel vostro codice:

```php
if (!Validators::isEmail($email)) {
	throw new InvalidArgumentException('Invalid email address provided.');
}
```

Può inoltre verificare se il valore soddisfa i cosiddetti [tipi attesi |#Tipi attesi], cioè una stringa in cui le singole possibilità sono separate da una barra verticale `|`. Questo rende semplice verificare i tipi unione con [#is()]:

```php
if (!Validators::is($val, 'int|string|bool')) {
	// gestione del tipo non valido...
}
```

Permette anche di creare sistemi in cui le aspettative vanno scritte come stringhe (per esempio nelle annotazioni o nelle configurazioni) e i valori vanno poi validati rispetto a esse.

Potete anche dichiarare un'[asserzione |#assert()], che solleva un'eccezione se l'aspettativa non viene soddisfatta.


Tipi attesi
===========

I tipi attesi formano una stringa composta da una o più varianti separate da una barra `|`, come si scrivono i tipi in PHP (per esempio `'int|string|bool'`). È accettata anche la notazione nullable `?int`.

Un array in cui tutti gli elementi sono di un certo tipo si scrive nella forma `int[]`.

Alcuni tipi possono essere seguiti da due punti e da una lunghezza `:length` o da un intervallo `:[min]..[max]`, per esempio `string:10` (una stringa lunga 10 byte), `float:10..` (un numero maggiore o uguale a 10), `array:..10` (un array con al massimo dieci elementi) o `list:10..20` (un elenco con da 10 a 20 elementi), oppure da un'espressione regolare come `pattern:[0-9]+`.

Panoramica dei tipi e delle regole:

.[wide]
| Tipi di PHP  ||
|--------------------------
| `array` .{width: 140px} | si può indicare un intervallo per il numero di elementi
| `bool`     |
| `boolean`  | alias di `bool`
| `float`    | si può indicare un intervallo per il valore
| `int`      | si può indicare un intervallo per il valore
| `integer`  | alias di `int`
| `null`     |
| `object`   |
| `resource` |
| `scalar`   | `int|float|bool|string`
| `string`   | si può indicare un intervallo per la lunghezza in byte
| `callable` |
| `iterable` |
| `mixed`    |
|------------------------------------------------
| Pseudo-tipi  ||
|------------------------------------------------
| `list`      | array indicizzato, si può indicare un intervallo per il numero di elementi
| `none`      | valore vuoto: `''`, `null`, `false`, `0`, `0.0`, `[]`
| `number`    | `int|float`
| `numeric`   | [numero, anche in forma di stringa |#isNumeric()]
| `numericint`| [intero, anche in forma di stringa |#isNumericInt()]
| `unicode`   | [stringa UTF-8 |#isUnicode()], si può indicare un intervallo per la lunghezza in caratteri
|------------------------------------------------
| Classe di caratteri (non deve essere una stringa vuota) ||
|------------------------------------------------
| `alnum`  | tutti i caratteri sono alfanumerici
| `alpha`  | tutti i caratteri sono lettere `[A-Za-z]`
| `digit`  | tutti i caratteri sono cifre
| `lower`  | tutti i caratteri sono lettere minuscole `[a-z]`
| `space`  | tutti i caratteri sono spazi bianchi
| `upper`  | tutti i caratteri sono lettere maiuscole `[A-Z]`
| `xdigit` | tutti i caratteri sono cifre esadecimali `[0-9A-Fa-f]`
|------------------------------------------------
| Validazione della sintassi  ||
|------------------------------------------------
| `pattern`   | un'espressione regolare a cui deve corrispondere l'**intera** stringa
| `email`     | [E-mail |#isEmail()]
| `identifier`| [identificatore PHP |#isPhpIdentifier()]
| `url`       | [URL |#isUrl()]
| `uri`       | [URI |#isUri()]
|------------------------------------------------
| Validazione dell'ambiente  ||
|------------------------------------------------
| `class`     | è il nome di una classe esistente
| `interface` | è il nome di un'interfaccia esistente
| `directory` | è il percorso di una directory esistente
| `file`      | è il percorso di un file esistente


Asserzione
==========


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

Verifica che il valore sia uno dei [tipi attesi |#Tipi attesi] separati da una barra. In caso contrario solleva [api:Nette\Utils\AssertionException]. La parola `variable` nel messaggio dell'eccezione si può sostituire con il parametro `$label`.

```php
Validators::assert('Nette', 'string:5'); // OK (la stringa 'Nette' ha 5 byte)
Validators::assert('Lorem ipsum dolor sit', 'string:78');
// AssertionException: The variable expects to be string in range 78, string 'Lorem ipsum dolor sit' given.
```


assertField(array $array, string|int $key, ?string $expected=null, string $label="item '%' in array"): void .[method]
---------------------------------------------------------------------------------------------------------------------

Verifica che l'elemento con chiave `$key` nell'array `$array` sia uno dei [tipi attesi |#Tipi attesi] separati da una barra. In caso contrario solleva [api:Nette\Utils\AssertionException]. La stringa `item '%' in array` nel messaggio dell'eccezione si può sostituire con il parametro `$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.
```


Validatori
==========


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

Controlla se il valore è uno dei [tipi attesi |#Tipi attesi] separati da una barra.

```php
Validators::is(1, 'int|float');  // true
Validators::is(23, 'int:0..10'); // false (23 è fuori dall'intervallo 0-10)
Validators::is('Nette Framework', 'string:15');     // true, la lunghezza è di 15 byte
Validators::is('Nette Framework', 'string:8..');    // true
Validators::is('Nette Framework', 'string:30..40'); // false
```


everyIs(iterable $values, string $expected): bool .[method]
-----------------------------------------------------------

Controlla se ogni valore dell'iterabile è uno dei [tipi attesi |#Tipi attesi] separati da una barra. Funziona come [#is()] applicato a ogni elemento.

```php
$list = ['Nette', 'Framework', 2020];
Validators::everyIs($list, 'string');     // false (2020 non è una stringa)
Validators::everyIs($list, 'string|int'); // true
```


isEmail(string $value): bool .[method]
--------------------------------------

Verifica che il valore sia un indirizzo e-mail valido. Non verifica che il dominio esista davvero, controlla solo la sintassi. La funzione tiene conto anche dei futuri [TLD|https://it.wikipedia.org/wiki/Dominio_di_primo_livello], che possono essere anche in unicode.

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


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

Controlla se il valore rientra nell'intervallo indicato `[min, max]`, dove il limite superiore o inferiore si può omettere (`null`). Si possono confrontare numeri, stringhe e oggetti DateTime.

Se mancano entrambi i limiti (`[null, null]`) oppure il valore è `null`, restituisce `false`.

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


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

Controlla se il valore è `0`, `''`, `false`, `null`, `0.0` o `[]`.

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

Controlla se il valore è un numero oppure un numero rappresentato come stringa.

```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 (la notazione scientifica non è accettata)
```


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

Controlla se il valore è un intero oppure un intero rappresentato come stringa.

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

Controlla se il valore è un identificatore sintatticamente valido in PHP (per esempio per i nomi di classi, metodi, funzioni ecc.).

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


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

Stabilisce se `$type` è un tipo integrato di PHP (per esempio `string`, `int`, `array`, `bool`). In caso contrario si presume che sia il nome di una classe.

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


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

Controlla se la stringa di dichiarazione di tipo indicata è sintatticamente valida secondo le regole di PHP (compresi i tipi unione, intersezione e DNF).

```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 $name): bool .[method]
--------------------------------------------

Stabilisce se `$name` è una delle parole chiave di tipo interne `self`, `parent` o `static`.

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


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

Controlla se il valore è una stringa UTF-8 valida.

```php
Validators::isUnicode('nette'); // true
Validators::isUnicode('');      // true
Validators::isUnicode("\xA0");  // false (sequenza UTF-8 non valida)
```


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

Controlla se il valore è un indirizzo URL assoluto valido secondo la RFC 3986.

```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 (questa funzione non valida la parte userinfo)
Validators::isUrl('nette.org');                   // false (manca lo schema)
```


isUri(string $value): bool .[method]
------------------------------------

Verifica che il valore sia un indirizzo URI valido, cioè una stringa che inizia con uno schema sintatticamente valido seguito dai due punti (per esempio `http:`, `https:`, `mailto:`, `ftp:`).

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