Валидаторы значений
*******************

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


Установка:

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

Во всех примерах предполагается, что определён такой псевдоним класса:

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


Основы использования
====================

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

```php
if (!Validators::isEmail($email)) {
	throw new InvalidArgumentException('Invalid email address provided.');
}
```

Кроме того, он умеет проверять, отвечает ли значение так называемым [ожидаемым типам |#Ожидаемые типы] - строке, в которой отдельные варианты разделены вертикальной чертой `|`. Благодаря этому легко проверять объединённые типы с помощью [#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`     |
| `boolean`  | псевдоним для `bool`
| `float`    | можно задать диапазон значения
| `int`      | можно задать диапазон значения
| `integer`  | псевдоним для `int`
| `null`     |
| `object`   |
| `resource` |
| `scalar`   | `int|float|bool|string`
| `string`   | можно задать диапазон длины в байтах
| `callable` |
| `iterable` |
| `mixed`    |
|------------------------------------------------
| Псевдотипы  ||
|------------------------------------------------
| `list`      | индексированный массив, можно задать диапазон числа элементов
| `none`      | пустое значение: `''`, `null`, `false`, `0`, `0.0`, `[]`
| `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`     | [Email |#isEmail()]
| `identifier`| [идентификатор PHP |#isPhpIdentifier()]
| `url`       | [URL |#isUrl()]
| `uri`       | [URI |#isUri()]
|------------------------------------------------
| Проверка окружения  ||
|------------------------------------------------
| `class`     | существующее имя класса
| `interface` | существующее имя интерфейса
| `directory` | путь к существующему каталогу
| `file`      | путь к существующему файлу


Утверждение
===========


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

Проверяет, что значение относится к одному из [ожидаемых типов |#Ожидаемые типы], разделённых чертой. Если нет, выбрасывает [api:Nette\Utils\AssertionException]. Слово `variable` в сообщении исключения можно заменить параметром `$label`.

```php
Validators::assert('Nette', 'string:5'); // OK (строка 'Nette' занимает 5 байт)
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]
---------------------------------------------------------------------------------------------------------------------

Проверяет, что элемент с ключом `$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 (23 вне диапазона 0-10)
Validators::is('Nette Framework', 'string:15');     // true, длина 15 байт
Validators::is('Nette Framework', 'string:8..');    // true
Validators::is('Nette Framework', 'string:30..40'); // false
```


everyIs(iterable $values, string $expected): bool .[method]
-----------------------------------------------------------

Проверяет, относится ли каждое значение итерируемого объекта к одному из [ожидаемых типов |#Ожидаемые типы], разделённых чертой. Работает как [#is()], применённый к каждому элементу.

```php
$list = ['Nette', 'Framework', 2020];
Validators::everyIs($list, 'string');     // false (2020 не строка)
Validators::everyIs($list, 'string|int'); // true
```


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

Проверяет, что значение является корректным адресом электронной почты. Он не проверяет, существует ли домен на самом деле, проверяется только синтаксис. Функция учитывает и будущие [домены верхнего уровня|https://ru.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 (равнозначно [5, null])
Validators::isInRange(1, [5]);        // false
```


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

Проверяет, равно ли значение `0`, `''`, `false`, `null`, `0.0` или `[]`.

```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 (например, `string`, `int`, `array`, `bool`). Иначе предполагается, что это имя класса.

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


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

Проверяет, синтаксически ли корректна заданная строка объявления типа по правилам объявления типов PHP (включая объединения, пересечения и типы в дизъюнктивной нормальной форме).

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

Определяет, является ли `$name` одним из внутренних ключевых слов типов `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 (некорректная последовательность UTF-8)
```


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

Проверяет, является ли значение корректным абсолютным URL-адресом по RFC 3986.

```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 (часть userinfo этой функцией не проверяется)
Validators::isUrl('nette.org');                   // false (нет схемы)
```


isUri(string $value): bool .[method]
------------------------------------

Проверяет, что значение является корректным адресом URI, то есть строкой, начинающейся с синтаксически корректной схемы, за которой следует двоеточие (например, `http:`, `https:`, `mailto:`, `ftp:`).

```php
Validators::isUri('https://nette.org');           // true
Validators::isUri('mailto:gandalf@example.org');  // true
Validators::isUri('nette.org');                   // false (нет схемы)
```