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

Потрібно швидко і легко перевірити, що змінна містить, наприклад, дійсну адресу електронної пошти? Ось тут і стане в пригоді Nette\Utils\Validators, статичний клас із корисними функціями для перевірки значень.

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

composer require nette/utils

У всіх прикладах передбачається, що псевдонім уже створено:

use Nette\Utils\Validators;

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

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

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

Він також може перевірити, чи є значення очікуваним типом, який являє собою рядок, де опції розділені косою рискою |. Таким чином, ми можемо легко перевірити кілька типів за допомогою if():

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

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

Ми також можемо поставити запит assert() на очікувані типи, який у разі невиконання викидає виняток.

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

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

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

Затвердження

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

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

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

Перевіряє, що елемент під ключем $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
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

Перевіряє, чи є значення дійсною адресою електронної пошти. Він не перевіряє, чи існує домен насправді, перевіряється тільки синтаксис. Функція також враховує майбутні ДВУ, які можуть бути в юнікоді.

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
Validators::isInRange(1, [5]);        // false

isNone(mixed $value): bool

Перевіряє, що значення дорівнює 0, '', false або null.

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. В іншому випадку це ім'я класу.

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

isTypeDeclaration(string $type): bool

Перевіряє, чи є дане оголошення типу синтаксично допустимим.

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

Перевіряє, чи є $type одним із внутрішніх типів 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

isUrl(mixed $value): bool

Перевіряє, чи є значення дійсним URL.

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

Перевіряє, чи є значення дійсною адресою URI, яка фактично являє собою рядок, що починається з синтаксично допустимої схеми.

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