Валидатори на стойности

Трябва бързо и лесно да проверите дали дадена променлива съдържа валиден имейл адрес, например? Тук на помощ идва 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

Проверява дали стойността е валиден имейл адрес. Не се проверява дали домейнът действително съществува, проверява се само синтаксисът. Функцията взема предвид и бъдещите TLD, които може да са в 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
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