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