Validátory hodnot

Potřebujete rychle a jednoduše ověřit, že v proměnné je například platná e-mailová adresa? To se vám bude hodit Nette\Utils\Validators, statická třída s užitečnými funkcemi pro validaci hodnot.

Instalace:

composer require nette/utils

Všechny příklady předpokládají vytvořený alias:

use Nette\Utils\Validators;

Základní použití

Třída disponuje řadou metod pro kontrolu hodnot, jako třeba isList(), isUnicode(), isEmail(), isUrl() atd. pro využití ve vašem kódu:

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

Dále umí oveřit, zda hodnota je tzv. očekávaný typy, což je řetězec, kde se jednotlivé možnosti oddělují svislítkem |. Můžeme tak snadno oveřit více typů pomocí if():

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

Ale také nám to dává možnost vytvořit si systém, kde je potřeba očekávání zapisovat jako řetězce (například v anotacích nebo konfiguraci) a pak podle nich ověřovat hodnoty.

Na očekávané typy lze dát i požadavek assert(), který když není splněn, tak se vyhodí výjimka.

Očekávané typy

Očekávané typy tvoří řetězec skládající se z jedné čí více variant oddělených svislítkem |, podobně jako se zapisují typy v PHP (např. 'int|string|bool'). Akceptuje se i nullable zápis ?int.

Pole, kde všechny prvky jsou určitého typu, se zapíše ve tvaru int[].

Za některými typy může následovat dvojtečka a délka :length nebo rozsah :[min]..[max], např. string:10 (řetězec o délce 10 bytů), float:10.. (číslo 10 a větší), array:..10 (pole do deseti prvků) nebo list:10..20 (list s 10 až 20 prvky), případně regulární výraz u pattern:[0-9]+.

Přehled typů a pravidel:

PHP typy
`array`	lze uvést rozsah pro počet prvků
`bool`
`float`	lze uvést rozsah pro hodnotu
`int`	lze uvést rozsah pro hodnotu
`null`
`object`
`resource`
`scalar`	int\|float\|bool\|string
`string`	lze uvést rozsah pro délku v bajtech
`callable`
`iterable`
`mixed`
pseudo-typy
`list`	indexované pole, lze uvést rozsah pro počet prvků
`none`	prázdná hodnota: `''`, `null`, `false`
`number`	int\|float
`numeric`	číslo včetně textové reprezentace
`numericint`	celé číslo včetně textové reprezentace
`unicode`	UTF-8 řetězec, lze uvést rozsah pro délku ve znacích
znaková třída (nesmí být prázdný řetězec)
`alnum`	všechny znaky jsou alfanumerické
`alpha`	všechny znaky jsou písmena `[A-Za-z]`
`digit`	všechny znaky jsou číslice
`lower`	všechny znaky jsou malá písmena `[a-z]`
`space`	všechny znaky jsou mezery
`upper`	všechny znaky jsou velká písmena `[A-Z]`
`xdigit`	všechny znaky jsou hexadecimální číslice `[0-9A-Fa-f]`
ověření syntaxe
`pattern`	regulární výraz, kterému musí odpovídat celý řetězec
`email`	E-mail
`identifier`	PHP identifikátor
`url`	URL
`uri`	URI
ověřování prostředí
`class`	je existující třída
`interface`	je existující rozhraní
`directory`	je existující adresář
`file`	je existující soubor

Asserce

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

Ověřuje, že hodnota je jedním z očekávaných typů oddělených svislítkem. Pokud ne, vyhodí výjimku Nette\Utils\AssertionException. Slovo variable v textu výjimky lze nahradit za jiné parametrem $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

Ověřuje, zda prvek pod klíčem $key v poli $array je jedním z očekávaných typů oddělených svislítkem. Pokud ne, vyhodí výjimku Nette\Utils\AssertionException. Řetězec item '%' in array v textu výjimky lze nahradit za jiný parametrem $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.

Validátory

is($value, string $expected): bool

Ověří, zda hodnota je jedním z očekávaných typů oddělených svislítkem.

Validators::is(1, 'int|float');  // true
Validators::is(23, 'int:0..10'); // false
Validators::is('Nette Framework', 'string:15');     // true, délka je 15 bytů
Validators::is('Nette Framework', 'string:8..');    // true
Validators::is('Nette Framework', 'string:30..40'); // false

isEmail(mixed $value): bool

Ověří, zda je hodnota platná e-mailová adresa. Neověřuje se, zda doména skutečně existuje, ověřuje se pouze syntaxe. Funkce počítá i s budoucími TLD, které mohou být i v unicode.

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

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

Ověří, zda je hodnota v daném rozsahu [min, max], kde horní nebo spodní hranici můžeme vynechat (null). Lze porovnávat čísla, řetězce a objekty DateTime.

Pokud chybí obě hranice ([null, null]) nebo je hodnota null, vrací 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

Ověří, zda je hodnota 0, '', false or null.

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

isNumeric(mixed $value): bool

Ověří, zda je hodnota číslo nebo číslo zapsané v řetězci.

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

Ověří, zda je hodnota celé číslo nebo číslo zapsané v řetězci.

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

Ověří, zda je hodnota syntakticky platný identifikátor v PHP, například pro názvy tříd, metod, funkcí apod.

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

isBuiltinType(string $type): bool

Zjistí, zda je $type vestavěný typ PHP. V opačném případě jde o název třídy.

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

isTypeDeclaration(string $type): bool

Checks whether the given type declaration is syntactically 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

Zjistí, zda je $type jedním z interních typů self, parent, static.

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

isUnicode(mixed $value): bool

Ověří, zda je hodnota platný UTF-8 string.

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

isUrl(mixed $value): bool

Ověří, zda je hodnota platná URL adresa.

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

Ověří, zda je hodnota platná URI adresa, tedy vlastně řetězec začínající syntakticky platným schématem.

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

Nette Documentation Preview