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)
```
Validatori di valori
Avete bisogno di verificare in modo rapido e semplice che una variabile contenga, per esempio, un indirizzo
e-mail valido? Allora vi tornerà utile Nette\Utils\Validators, una classe statica con utili
funzioni per validare i valori.
Installazione:
composer require nette/utils
Tutti gli esempi presuppongono che sia definito questo alias di classe:
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:
if (!Validators::isEmail($email)) {
throw new InvalidArgumentException('Invalid email address provided.');
}
Può inoltre verificare se il valore soddisfa i cosiddetti 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():
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, 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:
| Tipi di PHP |
array |
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 |
|
|
|
numericint |
intero, anche in forma di stringa |
|
|
|
unicode |
stringa UTF-8, 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 |
|
|
|
identifier |
identificatore PHP |
|
|
|
url |
URL |
|
|
|
uri |
URI |
|
|
|
| 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
Verifica che il valore sia uno dei tipi attesi separati da una barra. In caso contrario solleva
Nette\Utils\AssertionException. La parola
variable nel messaggio dell'eccezione si può sostituire con il parametro $label.
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
Verifica che l'elemento con chiave $key nell'array $array sia uno dei tipi
attesi separati da una barra. In caso contrario solleva Nette\Utils\AssertionException. La stringa
item '%' in array nel messaggio dell'eccezione si può sostituire con il parametro $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.
Validatori
is ($value, string $expected): bool
Controlla se il valore è uno dei tipi attesi separati da una barra.
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
Controlla se ogni valore dell'iterabile è uno dei tipi attesi separati da una barra. Funziona
come is() applicato a ogni elemento.
$list = ['Nette', 'Framework', 2020];
Validators::everyIs($list, 'string'); // false (2020 non è una stringa)
Validators::everyIs($list, 'string|int'); // true
isEmail (string $value): bool
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, che possono
essere anche in unicode.
Validators::isEmail('example@nette.org'); // true
Validators::isEmail('example@localhost'); // false
Validators::isEmail('nette'); // false
isInRange (mixed $value, array
$range): bool
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.
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
Controlla se il valore è 0, '', false, null, 0.0
o [].
Validators::isNone(0); // true
Validators::isNone(''); // true
Validators::isNone(false); // true
Validators::isNone(null); // true
Validators::isNone('nette'); // false
isNumeric (mixed $value): bool
Controlla se il valore è un numero oppure un numero rappresentato come stringa.
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
Controlla se il valore è un intero oppure un intero rappresentato come stringa.
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
Controlla se il valore è un identificatore sintatticamente valido in PHP (per esempio per i nomi di classi, metodi,
funzioni ecc.).
Validators::isPhpIdentifier(''); // false
Validators::isPhpIdentifier('Hello1'); // true
Validators::isPhpIdentifier('1Hello'); // false
Validators::isPhpIdentifier('one two'); // false
isBuiltinType (string $type): bool
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.
Validators::isBuiltinType('string'); // true
Validators::isBuiltinType('Foo'); // false
isTypeDeclaration (string
$type): bool
Controlla se la stringa di dichiarazione di tipo indicata è sintatticamente valida secondo le regole di PHP (compresi i tipi
unione, intersezione e DNF).
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
Stabilisce se $name è una delle parole chiave di tipo interne self, parent o
static.
Validators::isClassKeyword('self'); // true
Validators::isClassKeyword('Foo'); // false
isUnicode (mixed $value): bool
Controlla se il valore è una stringa UTF-8 valida.
Validators::isUnicode('nette'); // true
Validators::isUnicode(''); // true
Validators::isUnicode("\xA0"); // false (sequenza UTF-8 non valida)
isUrl (string $value): bool
Controlla se il valore è un indirizzo URL assoluto valido secondo la RFC 3986.
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
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:).
Validators::isUri('https://nette.org'); // true
Validators::isUri('mailto:gandalf@example.org'); // true
Validators::isUri('nette.org'); // false (manca lo schema)