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:

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)