Валидатори на стойности
***********************

.[perex]
Трябва бързо и лесно да проверите дали дадена променлива съдържа валиден имейл адрес, например? Тук на помощ идва [api:Nette\Utils\Validators], статичен клас с полезни функции за валидиране на стойности.


Настройка:

```shell
composer require nette/utils
```

Всички примери предполагат, че псевдонимът вече е създаден:

```php
use Nette\Utils\Validators;
```


Основно използване .[#toc-basic-usage]
======================================

Класът има редица методи за проверка на стойности, като [isList( |#isList]), [isUnicode( |#isUnicode]), [isEmail() |#isEmail], [isUrl() |#isUrl] и др., които можете да използвате в кода си:

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

Той може също така да провери дали стойността е от [очаквания тип |#Expected-Types], който представлява низ, в който опциите са разделени с наклонена черта `|`. По този начин можем лесно да проверяваме няколко типа с помощта на [if() |#if()]:

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

Но също така ни дава система, в която трябва да записваме очаквания като низове (например в анотации или конфигурации) и след това да проверяваме стойностите спрямо тях.

Можем също така да поставим заявка [assert() |#assert] за очакваните типове, която хвърля изключение, ако не успее.


Очаквани видове .[#toc-expected-types]
======================================

Очакваните типове образуват низ, състоящ се от един или повече варианти, разделени с вертикална черта `|`, podobně jako se zapisují typy v PHP (např. `'int|string|bool')`. Приема се и нулевият запис `?int`.

Масив, в който всички елементи имат определен тип, се записва като `int[]`.

Някои типове могат да бъдат последвани от двоеточие и дължина `:length` или диапазон. `:[min]..[max]`Например `string:10` (низ от 10 байта), `float:10..` (число от 10 или повече), `array:..10` (масив от до десет елемента) или `list:10..20` (списък от 10 до 20 елемента), или регулярният израз u `pattern:[0-9]+`.

Преглед на видовете и правилата:

.[wide]
| PHP типове ||
|--------------------------
| `array` .{width: 140px} || За броя на елементите може да се посочи диапазон.
|| `bool` |
|| `float` || За дадена стойност може да бъде зададен диапазон.
| `int` | може да се зададе диапазон от стойности.
| `null` |
| `object` |
| `resource` |
| `scalar` | int\|float\|bool\|string
| `string` | За дължината в байтове може да се зададе диапазон.
| `callable` |
| `iterable` |
| `mixed` |
|--------------------------
| псевдотипове ||
|------------------------------------------------
| `list` | [индексиран масив |#isList], може да се зададе диапазон за броя на елементите
| `none` | празна стойност: `''`, `null`, `false`
| `number` | int\|float
| `numeric` | [число, включително текстово представяне |#isNumeric]
| `numericint`| [цяло число |#isNumericInt], включително текстово представяне
| `unicode` | [UTF-8 низ |#isUnicode], може да се зададе диапазон на дължината на символите.
|--------------------------
| клас символи (не трябва да е празен низ)||
|------------------------------------------------
| `alnum` | всички буквено-цифрови символи
| `alpha` | всички символи са букви `[A-Za-z]`
| `digit` | всички символи са числа
| `lower` | всички символи са малки букви `[a-z]`
| `space` | всички символи са интервали
| `upper` | всички символи са главни букви `[A-Z]`
| `xdigit` | всички символи са шестнадесетични цифри `[0-9A-Fa-f]`
|--------------------------
| проверка на синтаксиса ||
|------------------------------------------------
| `pattern` | регулярен израз, който трябва да съответства на **всички** редове
| `email` | [E-mail |#isEmail]
| `identifier`| [Идентификатор на PHP |#isPhpIdentifier]
| `url` | [URL |#isUrl]
| `uri` | [URI |#isUri]
|--------------------------
| удостоверяване на средата ||
|------------------------------------------------
| `class` | това е съществуващ клас
| `interface` | това е съществуващ интерфейс
| `directory` | това е съществуваща директория
| `file` | това е съществуващ файл


Твърдение .[#toc-assertion]
===========================


assert($value, string $expected, string $label='variable'): void .[method]
--------------------------------------------------------------------------

Проверява дали стойността е един от [очакваните типове |#Expected-Types], разделени със звездичка. В противен случай се изхвърля изключението [api:Nette\Utils\AssertionException]. Думата `variable` в текста на изключението може да бъде заменена с друг параметър `$label`.

```php
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 .[method]
-------------------------------------------------------------------------------------------------------

Проверява се дали елементът под ключа `$key` в полето `$array` е един от [очакваните типове |#Expected-Types], разделени със звездичка. В противен случай се изхвърля изключение [api:Nette\Utils\AssertionException]. Реда `item '%' in array` в текста на изключението може да бъде заменен с друг параметър `$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.
```


Удостоверители .[#toc-validators]
=================================


is($value, string $expected): bool .[method]
--------------------------------------------

Проверява дали стойността е един от [очакваните типове |#Expected-Types], разделени със звездичка.

```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 bytů
Validators::is('Nette Framework', 'string:8..');    // true
Validators::is('Nette Framework', 'string:30..40'); // false
```


isEmail(mixed $value): bool .[method]
-------------------------------------

Проверява дали стойността е валиден имейл адрес. Не се проверява дали домейнът действително съществува, проверява се само синтаксисът. Функцията взема предвид и бъдещите [TLD, които |https://cs.wikipedia.org/wiki/Doména_nejvyššího_řádu] може да са в Unicode.

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


isInRange(mixed $value, array $range): bool .[method]
-----------------------------------------------------

Проверява дали стойността е в рамките на зададен диапазон `[min, max]`където може да се пропусне горна или долна граница (`null`). Могат да се сравняват числа, низове и обекти от тип DateTime.

Ако липсват и двете граници (`[null, null]`) или се връща стойността `null`, `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]
------------------------------------

Проверява се дали стойността е `0`, `''`, `false` или `null`.

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

Проверява дали стойността е число или число, записано в низ.

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

Проверява дали стойността е цяло число или число, записано в низ.

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

Проверява дали стойността е синтактично валиден идентификатор в PHP, например за имена на класове, методи, функции и т.н.

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


isBuiltinType(string $type): bool .[method]
-------------------------------------------

Проверява дали `$type` е вграден тип в PHP. Ако не, това е име на клас.

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


isTypeDeclaration(string $type): bool .[method]
-----------------------------------------------

Проверява дали дадената декларация на типа е синтактично валидна.

```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 $type): bool .[method]
--------------------------------------------

Проверява се дали `$type` е един от вътрешните типове `self`, `parent`, `static`.

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


isUnicode(mixed $value): bool .[method]
---------------------------------------

Проверява дали стойността е валиден низ в UTF-8.

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


isUrl(mixed $value): bool .[method]
-----------------------------------

Проверява дали стойността е валиден URL адрес.

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

Проверява дали стойността е валиден URI адрес, който всъщност е низ, започващ със синтактично валиден шаблон.

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