validators.texy

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

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

Проверяет, является ли значение действительным адресом электронной почты. Он не проверяет, существует ли домен на самом деле, проверяется только синтаксис. Функция также учитывает будущие [ДВУ |https://cs.wikipedia.org/wiki/Doména_nejvyššího_řádu], которые могут быть в юникоде.

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