Validatorji vrednosti

Potrebujete hitro in enostavno preveriti, ali je v spremenljivki na primer veljaven e-poštni naslov? Za to vam bo prišel prav Nette\Utils\Validators, statični razred z uporabnimi funkcijami za validacijo vrednosti.

Namestitev:

composer require nette/utils

Vsi primeri predpostavljajo ustvarjen vzdevek:

use Nette\Utils\Validators;

Osnovna uporaba

Razred ponuja vrsto metod za preverjanje vrednosti, kot so isList(), isUnicode(), isEmail(), isUrl() itd., za uporabo v vaši kodi:

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

Poleg tega lahko preveri, ali je vrednost t.i. pričakovani tipi, kar je niz, kjer so posamezne možnosti ločene z navpičnico |. Tako lahko enostavno preverimo več tipov z uporabo is():

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

Vendar nam to daje tudi možnost ustvariti sistem, kjer je treba pričakovanja zapisati kot nize (na primer v anotacijah ali konfiguraciji) in nato glede na njih preverjati vrednosti.

Za pričakovane tipe lahko postavimo tudi zahtevo assert(), ki, če ni izpolnjena, sproži izjemo.

Pričakovani tipi

Pričakovani tipi tvorijo niz, sestavljen iz ene ali več različic, ločenih z navpičnico |, podobno kot se zapisujejo tipi v PHP (npr. 'int|string|bool'). Sprejema se tudi nullable zapis ?int.

Polje, kjer so vsi elementi določenega tipa, se zapiše v obliki int[].

Nekaterim tipom lahko sledi dvopičje in dolžina :length ali obseg :[min]..[max], npr. string:10 (niz dolžine 10 bajtov), float:10.. (število 10 in večje), array:..10 (polje do desetih elementov) ali list:10..20 (seznam z 10 do 20 elementi), ali pa regularni izraz pri pattern:[0-9]+.

Pregled tipov in pravil:

Asercije

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

Preverja, ali je vrednost eden od pričakovanih tipov, ločenih z navpičnico. Če ne, sproži izjemo Nette\Utils\AssertionException. Besedo variable v besedilu izjeme lahko nadomestite z drugo s parametrom $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

Preverja, ali je element pod ključem $key v polju $array eden od pričakovanih tipov, ločenih z navpičnico. Če ne, sproži izjemo Nette\Utils\AssertionException. Niz item '%' in array v besedilu izjeme lahko nadomestite z drugim s parametrom $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.

Validatorji

is ($value, string $expected): bool

Preveri, ali je vrednost eden od pričakovanih tipov, ločenih z navpičnico.

Validators::is(1, 'int|float');  // true
Validators::is(23, 'int:0..10'); // false
Validators::is('Nette Framework', 'string:15');     // true, dolžina je 15 bajtov
Validators::is('Nette Framework', 'string:8..');    // true
Validators::is('Nette Framework', 'string:30..40'); // false

isEmail (mixed $value): bool

Preveri, ali je vrednost veljaven e-poštni naslov. Ne preverja se, ali domena dejansko obstaja, preverja se samo sintaksa. Funkcija upošteva tudi prihodnje TLD, ki so lahko tudi v unicode.

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

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

Preveri, ali je vrednost v danem obsegu [min, max], kjer lahko zgornjo ali spodnjo mejo izpustimo (null). Lahko se primerjajo števila, nizi in objekti DateTime.

Če manjkata obe meji ([null, null]) ali je vrednost null, vrne 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

Preveri, ali je vrednost 0, '', false ali null.

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

isNumeric (mixed $value): bool

Preveri, ali je vrednost število ali število, zapisano v nizu.

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

Preveri, ali je vrednost celo število ali celo število, zapisano v nizu.

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

Preveri, ali je vrednost sintaktično veljaven identifikator v PHP, na primer za imena razredov, metod, funkcij itd.

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

isBuiltinType (string $type): bool

Ugotovi, ali je $type vgrajen tip PHP. V nasprotnem primeru gre za ime razreda.

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

isTypeDeclaration (string $type): bool

Preveri, ali je dana deklaracija tipa sintaktično veljavna.

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

Ugotovi, ali je $type eden od internih tipov self, parent, static.

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

isUnicode (mixed $value): bool

Preveri, ali je vrednost veljaven UTF-8 niz.

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

isUrl (mixed $value): bool

Preveri, ali je vrednost veljaven URL naslov.

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

Preveri, ali je vrednost veljaven URI naslov, torej pravzaprav niz, ki se začne s sintaktično veljavno shemo.

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