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

Трябва бързо и лесно да проверите дали в променлива има например валиден имейл адрес? За това ще ви бъде полезен 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(), което ако не е изпълнено, се хвърля изключение.

Очаквани типове

Очакваните типове представляват низ, състоящ се от една или повече варианти, разделени с вертикална черта |, подобно на начина, по който се записват типовете в 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]+.

Преглед на типовете и правилата:

Assertions

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, дължината е 15 байта
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