Validatori de valori

Aveți nevoie să verificați rapid și simplu dacă o variabilă conține, de exemplu, o adresă de e-mail validă? Atunci vă va fi utilă Nette\Utils\Validators, o clasă statică cu funcții utile pentru validarea valorilor.

Instalare:

composer require nette/utils

Toate exemplele presupun crearea unui alias:

use Nette\Utils\Validators;

Utilizare de bază

Clasa dispune de o serie de metode pentru verificarea valorilor, cum ar fi isList(), isUnicode(), isEmail(), isUrl() etc., pentru a fi utilizate în codul dumneavoastră:

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

În plus, poate verifica dacă valoarea este unul dintre așa-numitele tipuri așteptate, care este un șir în care opțiunile individuale sunt separate prin bară verticală |. Putem astfel verifica ușor mai multe tipuri folosind is():

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

Dar ne oferă și posibilitatea de a crea un sistem în care este necesar să scriem așteptările ca șiruri (de exemplu, în adnotări sau configurație) și apoi să verificăm valorile conform acestora.

Pentru tipurile așteptate se poate aplica și o cerință assert(), care, dacă nu este îndeplinită, aruncă o excepție.

Tipuri așteptate

Tipurile așteptate formează un șir compus dintr-una sau mai multe variante separate prin bară verticală |, similar modului în care se scriu tipurile în PHP (de ex. 'int|string|bool'). Se acceptă și notația nullable ?int.

Un array în care toate elementele sunt de un anumit tip se scrie în forma int[].

După unele tipuri poate urma două puncte și lungimea :length sau intervalul :[min]..[max], de ex. string:10 (șir cu lungimea de 10 octeți), float:10.. (număr 10 și mai mare), array:..10 (array cu până la zece elemente) sau list:10..20 (listă cu 10 până la 20 de elemente), sau o expresie regulată la pattern:[0-9]+.

Prezentare generală a tipurilor și regulilor:

Aserțiuni

assert ($value, string $expected, string $label='variable'): void

Verifică dacă valoarea este unul dintre tipurile așteptate separate prin bară verticală. Dacă nu, aruncă excepția Nette\Utils\AssertionException. Cuvântul variable din textul excepției poate fi înlocuit cu altul prin parametrul $label.

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

Verifică dacă elementul cu cheia $key din array-ul $array este unul dintre tipurile așteptate separate prin bară verticală. Dacă nu, aruncă excepția Nette\Utils\AssertionException. Șirul item '%' in array din textul excepției poate fi înlocuit cu altul prin parametrul $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

Verifică dacă valoarea este unul dintre tipurile așteptate separate prin bară verticală.

Validators::is(1, 'int|float');  // true
Validators::is(23, 'int:0..10'); // false
Validators::is('Nette Framework', 'string:15');     // true, lungimea este 15 octeți
Validators::is('Nette Framework', 'string:8..');    // true
Validators::is('Nette Framework', 'string:30..40'); // false

isEmail (mixed $value): bool

Verifică dacă valoarea este o adresă de e-mail validă. Nu se verifică dacă domeniul există efectiv, se verifică doar sintaxa. Funcția ia în considerare și viitoarele TLD, care pot fi și în unicode.

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

isInRange (mixed $value, array $range): bool

Verifică dacă valoarea se află în intervalul dat [min, max], unde limita superioară sau inferioară poate fi omisă (null). Se pot compara numere, șiruri și obiecte DateTime.

Dacă lipsesc ambele limite ([null, null]) sau valoarea este null, returnează false.

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

Verifică dacă valoarea este 0, '', false sau null.

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

isNumeric (mixed $value): bool

Verifică dacă valoarea este un număr sau un număr scris într-un șir.

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

Verifică dacă valoarea este un număr întreg sau un număr întreg scris într-un șir.

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

Verifică dacă valoarea este un identificator sintactic valid în PHP, de exemplu pentru nume de clase, metode, funcții etc.

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

isBuiltinType (string $type): bool

Determină dacă $type este un tip încorporat PHP. În caz contrar, este numele unei clase.

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

isTypeDeclaration (string $type): bool

Verifică dacă declarația de tip dată este sintactic validă.

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

Determină dacă $type este unul dintre tipurile interne self, parent, static.

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

isUnicode (mixed $value): bool

Verifică dacă valoarea este un șir UTF-8 valid.

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

isUrl (mixed $value): bool

Verifică dacă valoarea este o adresă URL validă.

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

Verifică dacă valoarea este o adresă URI validă, adică de fapt un șir care începe cu o schemă sintactic validă.

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