Validátory hodnot
*****************
.[perex]
Potřebujete rychle a jednoduše ověřit, že v proměnné je například platná e-mailová adresa? K tomu se vám bude hodit [api:Nette\Utils\Validators], statická třída s užitečnými funkcemi pro validaci hodnot.
Instalace:
```shell
composer require nette/utils
```
Všechny příklady předpokládají vytvořený alias:
```php
use Nette\Utils\Validators;
```
Základní použití
================
Třída disponuje řadou metod pro kontrolu hodnot, jako třeba [#isUnicode()], [#isEmail()], [#isUrl()] atd. pro využití ve vašem kódu:
```php
if (!Validators::isEmail($email)) {
throw new InvalidArgumentException;
}
```
Dále umí ověřit, zda hodnota odpovídá tzv. [očekávaným typům |#Očekávané typy], což je řetězec, kde se jednotlivé možnosti oddělují svislítkem `|`. Můžeme tak snadno ověřit více typů pomocí [#is()]:
```php
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 klást i požadavek [#assert()]; pokud není splněn, vyhodí se výjimka.
Očekávané typy
==============
Očekávané typy tvoří řetězec skládající se z jedné či 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 bajtů), `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:
.[wide]
| PHP typy ||
|--------------------------
| `array` .{width: 140px} | lze uvést rozsah pro počet prvků
| `bool` |
| `boolean` | alias pro `bool`
| `float` | lze uvést rozsah pro hodnotu
| `int` | lze uvést rozsah pro hodnotu
| `integer` | alias pro `int`
| `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`, `0`, `0.0`, `[]`
| `number` | `int|float`
| `numeric` | [číslo včetně textové reprezentace |#isNumeric]
| `numericint`| [celé číslo včetně textové reprezentace |#isNumericInt]
| `unicode` | [UTF-8 řetězec |#isUnicode], 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 |#isEmail]
| `identifier`| [PHP identifikátor |#isPhpIdentifier]
| `url` | [URL |#isUrl]
| `uri` | [URI |#isUri]
|--------------------------
| 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 .[method]
--------------------------------------------------------------------------
Ověřuje, že hodnota je jedním z [očekávaných typů |#Očekávané typy] oddělených svislítkem. Pokud ne, vyhodí výjimku [api:Nette\Utils\AssertionException]. Slovo `variable` v textu výjimky lze nahradit za jiné parametrem `$label`.
```php
Validators::assert('Nette', 'string:5'); // OK
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 .[method]
---------------------------------------------------------------------------------------------------------------------
Ověřuje, zda prvek pod klíčem `$key` v poli `$array` je jedním z [očekávaných typů |#Očekávané typy] oddělených svislítkem. Pokud ne, vyhodí výjimku [api:Nette\Utils\AssertionException]. Řetězec `item '%' in array` v textu výjimky lze nahradit za jiný parametrem `$label`.
```php
$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 .[method]
--------------------------------------------
Ověří, zda hodnota je jedním z [očekávaných typů |#Očekávané typy] oddělených svislítkem.
```php
Validators::is(1, 'int|float'); // true
Validators::is(23, 'int:0..10'); // false
Validators::is('Nette Framework', 'string:15'); // true, délka je 15 bajtů
Validators::is('Nette Framework', 'string:8..'); // true
Validators::is('Nette Framework', 'string:30..40'); // false
```
everyIs(iterable $values, string $expected): bool .[method]
-----------------------------------------------------------
Ověří, zda je každá hodnota v poli jedním z [očekávaných typů |#Očekávané typy] oddělených svislítkem. Funguje jako [#is()] použité na každý prvek.
```php
$list = ['Nette', 'Framework', 2020];
Validators::everyIs($list, 'string'); // false (2020 není řetězec)
Validators::everyIs($list, 'string|int'); // true
```
isEmail(string $value): bool .[method]
--------------------------------------
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|https://cs.wikipedia.org/wiki/Doména_nejvyššího_řádu], které mohou být i v unicode.
```php
Validators::isEmail('example@nette.org'); // true
Validators::isEmail('example@localhost'); // false
Validators::isEmail('nette'); // false
```
isInRange(mixed $value, array $range): bool .[method]
-----------------------------------------------------
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`.
```php
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 .[method]
------------------------------------
Ověří, zda je hodnota `0`, `''`, `false`, `null`, `0.0` nebo `[]`.
```php
Validators::isNone(0); // true
Validators::isNone(''); // true
Validators::isNone(false); // true
Validators::isNone(null); // true
Validators::isNone('nette'); // false
```
isNumeric(mixed $value): bool .[method]
---------------------------------------
Ověří, zda je hodnota číslo nebo číslo zapsané v řetězci.
```php
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 .[method]
------------------------------------------
Ověří, zda je hodnota celé číslo nebo číslo zapsané v řetězci.
```php
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 .[method]
----------------------------------------------
Ověří, zda je hodnota syntakticky platný identifikátor v PHP, například pro názvy tříd, metod, funkcí apod.
```php
Validators::isPhpIdentifier(''); // false
Validators::isPhpIdentifier('Hello1'); // true
Validators::isPhpIdentifier('1Hello'); // false
Validators::isPhpIdentifier('one two'); // false
```
isBuiltinType(string $type): bool .[method]
-------------------------------------------
Zjistí, zda je `$type` vestavěný typ PHP. V opačném případě jde o název třídy.
```php
Validators::isBuiltinType('string'); // true
Validators::isBuiltinType('Foo'); // false
```
isTypeDeclaration(string $type): bool .[method]
-----------------------------------------------
Ověří, zda je zadaná typová deklarace syntakticky platná.
```php
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 .[method]
--------------------------------------------
Zjistí, zda je `$name` jedním z interních typů `self`, `parent`, `static`.
```php
Validators::isClassKeyword('self'); // true
Validators::isClassKeyword('Foo'); // false
```
isUnicode(mixed $value): bool .[method]
---------------------------------------
Ověří, zda je hodnota platný UTF-8 řetězec.
```php
Validators::isUnicode('nette'); // true
Validators::isUnicode(''); // true
Validators::isUnicode("\xA0"); // false
```
isUrl(string $value): bool .[method]
------------------------------------
Ověří, zda je hodnota platná URL adresa.
```php
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 .[method]
------------------------------------
Ověří, zda je hodnota platná URI adresa, tedy vlastně řetězec začínající syntakticky platným schématem.
```php
Validators::isUri('https://nette.org'); // true
Validators::isUri('mailto:gandalf@example.org'); // true
Validators::isUri('nette.org'); // false
```
{{maintitle: Validace hodnot v PHP s Nette Utils: e-mail, URL a typy}}
{{description: Rychle ověřte, že je v proměnné platný e-mail, URL, číslo nebo očekávaný typ. Třída Validators nabízí i aserce, které při neúspěchu vyhodí výjimku.}}
Validátory hodnot
Potřebujete rychle a jednoduše ověřit, že v proměnné je například platná e-mailová adresa? K tomu 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 isUnicode(), isEmail(), isUrl() atd. pro využití ve vašem kódu:
if (!Validators::isEmail($email)) {
throw new InvalidArgumentException;
}
Dále umí ověřit, zda hodnota odpovídá tzv. očekávaným typům, což je řetězec, kde
se jednotlivé možnosti oddělují svislítkem |. Můžeme tak snadno ověřit více typů pomocí is():
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 klást i požadavek assert(); pokud není splněn, vyhodí se výjimka.
Očekávané typy
Očekávané typy tvoří řetězec skládající se z jedné či 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 bajtů), 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 |
|
boolean |
alias pro bool |
float |
lze uvést rozsah pro hodnotu |
int |
lze uvést rozsah pro hodnotu |
integer |
alias pro int |
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, 0, 0.0,
[] |
|
|
|
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 in range 78, string 'Lorem ipsum dolor sit' given.
assertField (array $array, string|int
$key, ?string $expected=null, string $label="item '%' in array"): 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 bajtů
Validators::is('Nette Framework', 'string:8..'); // true
Validators::is('Nette Framework', 'string:30..40'); // false
everyIs (iterable $values, string
$expected): bool
Ověří, zda je každá hodnota v poli jedním z očekávaných typů oddělených
svislítkem. Funguje jako is() použité na každý prvek.
$list = ['Nette', 'Framework', 2020];
Validators::everyIs($list, 'string'); // false (2020 není řetězec)
Validators::everyIs($list, 'string|int'); // true
isEmail (string $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, null, 0.0
nebo [].
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
Ověří, zda je zadaná typová deklarace syntakticky platná.
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
Zjistí, zda je $name 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 řetězec.
Validators::isUnicode('nette'); // true
Validators::isUnicode(''); // true
Validators::isUnicode("\xA0"); // false
isUrl (string $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