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

.[perex]
Avete bisogno di verificare rapidamente e facilmente che una variabile contenga, ad esempio, un indirizzo email valido? Allora vi sarà utile [api:Nette\Utils\Validators], una classe statica con funzioni utili per la validazione dei valori.


Installazione:

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

Tutti gli esempi presuppongono la creazione di un alias:

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


Utilizzo di base
================

La classe dispone di numerosi metodi per il controllo dei valori, come [#isList()], [#isUnicode()], [#isEmail()], [#isUrl()] ecc. da utilizzare nel vostro codice:

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

Inoltre, può verificare se un valore è uno dei cosiddetti [tipi attesi|#Očekávané typy], che è una stringa in cui le singole opzioni sono separate da una barra verticale `|`. Possiamo così verificare facilmente più tipi utilizzando [#is()]:

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

Ma questo ci dà anche la possibilità di creare un sistema in cui è necessario scrivere le aspettative come stringhe (ad esempio in annotazioni o configurazioni) e poi verificare i valori in base ad esse.

Sui tipi attesi si può anche porre un requisito [#assert()], che se non soddisfatto, lancia un'eccezione.


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

I tipi attesi formano una stringa composta da una o più varianti separate da una barra verticale `|`, in modo simile a come vengono scritti i tipi in PHP (es. `'int|string|bool')`. Si accetta anche la notazione nullable `?int`.

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

Dopo alcuni tipi può seguire un due punti e una lunghezza `:length` o un intervallo `:[min]..[max]`, ad esempio `string:10` (stringa di 10 byte), `float:10..` (numero 10 o maggiore), `array:..10` (array fino a dieci elementi) o `list:10..20` (lista con 10-20 elementi), oppure un'espressione regolare per `pattern:[0-9]+`.

Panoramica dei tipi e delle regole:

.[wide]
| Tipi PHP   ||
|--------------------------
| `array` .{width: 140px} | è possibile specificare un intervallo per il numero di elementi
| `bool`     |
| `float`    | è possibile specificare un intervallo per il valore
| `int`      | è possibile specificare un intervallo per il valore
| `null`     |
| `object`   |
| `resource` |
| `scalar`   | int\|float\|bool\|string
| `string`   | è possibile specificare un intervallo per la lunghezza in byte
| `callable` |
| `iterable` |
| `mixed`    |
|--------------------------
| pseudo-tipi ||
|------------------------------------------------
| `list`      | [array indicizzato |#isList], è possibile specificare un intervallo per il numero di elementi
| `none`      | valore vuoto: `''`, `null`, `false`
| `number`    | int\|float
| `numeric`   | [numero inclusa la rappresentazione testuale |#isNumeric]
| `numericint`| [numero intero inclusa la rappresentazione testuale |#isNumericInt]
| `unicode`   | [stringa UTF-8 |#isUnicode], è possibile specificare un intervallo per la lunghezza in caratteri
|--------------------------
| classe di caratteri  (non può 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
| `upper`   | tutti i caratteri sono lettere maiuscole `[A-Z]`
| `xdigit`  | tutti i caratteri sono cifre esadecimali `[0-9A-Fa-f]`
|--------------------------
| validazione della sintassi  ||
|------------------------------------------------
| `pattern`   | 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`     | è una classe esistente
| `interface` | è un'interfaccia esistente
| `directory` | è una directory esistente
| `file`      | è un file esistente


Asserzioni
==========


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

Verifica che il valore sia uno dei [tipi attesi|#Očekávané typy] separati da una barra verticale. In caso contrario, lancia un'eccezione [api:Nette\Utils\AssertionException]. La parola `variable` nel testo dell'eccezione può essere sostituita con un'altra tramite il parametro `$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]
-------------------------------------------------------------------------------------------------------

Verifica se l'elemento con chiave `$key` nell'array `$array` è uno dei [tipi attesi|#Očekávané typy] separati da una barra verticale. In caso contrario, lancia un'eccezione [api:Nette\Utils\AssertionException]. La stringa `item '%' in array` nel testo dell'eccezione può essere sostituita con un'altra tramite 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]
--------------------------------------------

Verifica se il valore è uno dei [tipi attesi|#Očekávané typy] separati da una barra verticale.

```php
Validators::is(1, 'int|float');  // true
Validators::is(23, 'int:0..10'); // false
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
```


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

Verifica se il valore è un indirizzo email valido. Non viene verificato se il dominio esiste effettivamente, viene verificata 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]
-----------------------------------------------------

Verifica se il valore è nell'intervallo specificato `[min, max]`, dove il limite superiore o inferiore può essere omesso (`null`). È possibile confrontare numeri, stringhe e oggetti DateTime.

Se mancano entrambi i limiti (`[null, null]`) o il valore è `null`, restituisce `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]
------------------------------------

Verifica se il valore è `0`, `''`, `false` o `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]
---------------------------------------

Verifica se il valore è un numero o un numero scritto in una 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
```


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

Verifica se il valore è un numero intero o un numero intero scritto in una 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]
----------------------------------------------

Verifica se il valore è un identificatore sintatticamente valido in PHP, ad esempio per 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]
-------------------------------------------

Verifica se `$type` è un tipo built-in di PHP. Altrimenti, è un nome di classe.

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


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

Verifica se la dichiarazione di tipo specificata è sintatticamente valida.

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

Verifica se `$type` è uno dei tipi interni `self`, `parent`, `static`.

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


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

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

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


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

Verifica se il valore è un indirizzo URL valido.

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

Verifica se il valore è un indirizzo URI valido, ovvero una stringa che inizia con uno schema sintatticamente valido.

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