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

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

Установка:

composer require nette/utils

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

use Nette\Utils\Validators;

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

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

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

Кроме того, он умеет проверять, отвечает ли значение так называемым ожидаемым типам – строке, в которой отдельные варианты разделены вертикальной чертой |. Благодаря этому легко проверять объединённые типы с помощью is():

if (!Validators::is($val, 'int|string|bool')) {
	// Обработка неверного типа...
}

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

Вы можете также объявить утверждение, которое выбросит исключение, если ожидание не выполнено.

Ожидаемые типы

Ожидаемые типы образуют строку из одного или нескольких вариантов, разделённых чертой |, похоже на то, как типы записываются в 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]+.

Обзор типов и правил:

Утверждение

assert ($value, string $expected, string $label='variable'): void

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

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

Проверяет, что элемент с ключом $key в массиве $array относится к одному из ожидаемых типов, разделённых чертой. Если нет, выбрасывает Nette\Utils\AssertionException. Строку item '%' in array в сообщении исключения можно заменить параметром $label.

$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

Проверяет, относится ли значение к одному из ожидаемых типов, разделённых чертой.

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

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

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

isEmail (string $value): bool

Проверяет, что значение является корректным адресом электронной почты. Он не проверяет, существует ли домен на самом деле, проверяется только синтаксис. Функция учитывает и будущие домены верхнего уровня, которые могут быть и в Unicode.

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

isInRange (mixed $value, array $range): bool

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

Если отсутствуют обе границы ([null, null]) или значение равно null, возвращается false.

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

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

Validators::isNone(0); // true
Validators::isNone(''); // true
Validators::isNone(false); // true
Validators::isNone(null); // true
Validators::isNone('nette'); // false

isNumeric (mixed $value): bool

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

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

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

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

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

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

isBuiltinType (string $type): bool

Определяет, является ли $type встроенным типом PHP (например, string, int, array, bool). Иначе предполагается, что это имя класса.

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

isTypeDeclaration (string $type): bool

Проверяет, синтаксически ли корректна заданная строка объявления типа по правилам объявления типов 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

Определяет, является ли $name одним из внутренних ключевых слов типов self, parent или static.

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

isUnicode (mixed $value): bool

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

Validators::isUnicode('nette'); // true
Validators::isUnicode('');      // true
Validators::isUnicode("\xA0");  // false (некорректная последовательность UTF-8)

isUrl (string $value): bool

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

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

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

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