Валідатори значень
******************

.[perex]
Потрібно швидко та просто перевірити, чи є в змінній, наприклад, дійсна електронна адреса? Для цього вам знадобиться [api:Nette\Utils\Validators], статичний клас з корисними функціями для валідації значень.


Встановлення:

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

Усі приклади передбачають створений псевдонім:

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


Основне використання
====================

Клас має ряд методів для перевірки значень, таких як [#isUnicode()], [#isEmail()], [#isUrl()] тощо, для використання у вашому коді:

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

Крім того, він може перевірити, чи є значення так званим [очікуваним типом |#Очікувані типи], що є рядком, де окремі варіанти розділені вертикальною рискою `|`. Таким чином, ми можемо легко перевірити кілька типів за допомогою [#is()]:

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

Але це також дає нам можливість створити систему, де очікування потрібно записувати як рядки (наприклад, в анотаціях або конфігурації), а потім перевіряти значення відповідно до них.

До очікуваних типів можна також застосувати вимогу [#assert()], яка, якщо не виконана, викидає виняток.


Очікувані типи
==============

Очікувані типи утворюють рядок, що складається з одного або декількох варіантів, розділених вертикальною рискою `|`, подібно до того, як записуються типи в PHP (наприклад, `'int|string|bool'`). Також приймається запис nullable `?int`.

Масив, де всі елементи мають певний тип, записується у вигляді `int[]`.

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

Огляд типів та правил:

.[wide]
| PHP типи   ||
|--------------------------
| `array` .{width: 140px} | можна вказати діапазон для кількості елементів
| `bool`     |
| `float`    | можна вказати діапазон для значення
| `int`      | можна вказати діапазон для значення
| `null`     |
| `object`   |
| `resource` |
| `scalar`   | int\|float\|bool\|string
| `string`   | можна вказати діапазон для довжини в байтах
| `callable` |
| `iterable` |
| `mixed`    |
|--------------------------
| псевдо-типи ||
|------------------------------------------------
| `list`      | індексований масив, можна вказати діапазон для кількості елементів
| `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`      | є існуючим файлом


Assertions
==========


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

Перевіряє, що значення є одним з [очікуваних типів |#Очікувані типи], розділених вертикальною рискою. Якщо ні, викидає виняток [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` є одним з [очікуваних типів |#Очікувані типи], розділених вертикальною рискою. Якщо ні, викидає виняток [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.
```


Валідатори
==========


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

Перевіряє, чи значення є одним з [очікуваних типів |#Очікувані типи], розділених вертикальною рискою.

```php
Validators::is(1, 'int|float');  // true
Validators::is(23, 'int:0..10'); // false
Validators::is('Nette Framework', 'string:15');     // true, довжина 15 байтів
Validators::is('Nette Framework', 'string:8..');    // true
Validators::is('Nette Framework', 'string:30..40'); // false
```


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

Перевіряє, чи є значення дійсною електронною адресою. Не перевіряється, чи домен дійсно існує, перевіряється лише синтаксис. Функція враховує також майбутні [TLD|https://uk.wikipedia.org/wiki/Домен_найвищого_рівня], які можуть бути також в 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
```