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 |
|
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