Walidatory wartości

Potrzebujesz szybko i łatwo sprawdzić, czy zmienna zawiera na przykład prawidłowy adres e-mail? Przyda Ci się Nette\Utils\Validators, klasa statyczna z przydatnymi funkcjami do walidacji wartości.

Instalacja:

composer require nette/utils

Wszystkie przykłady zakładają, że zdefiniowany jest następujący alias klasy:

use Nette\Utils\Validators;

Podstawowe użycie

Klasa Validators udostępnia liczne metody do sprawdzania wartości, takie jak isUnicode(), isEmail(), isUrl() itd., do użycia w Twoim kodzie:

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

Ponadto potrafi sprawdzić, czy wartość spełnia tzw. oczekiwane typy, czyli string, w którym poszczególne opcje oddzielone są pionową kreską |. Dzięki temu łatwo sprawdzisz typy sumaryczne za pomocą is():

if (!Validators::is($val, 'int|string|bool')) {
	// obsługa nieprawidłowego typu...
}

Pozwala to też tworzyć systemy, w których oczekiwania trzeba zapisywać jako stringi (np. w adnotacjach albo konfiguracji), a następnie walidować wobec nich wartości.

Możesz też zadeklarować asercję, która zgłosi wyjątek, jeśli oczekiwanie nie zostanie spełnione.

Oczekiwane typy

Oczekiwane typy tworzą string złożony z jednego lub więcej wariantów oddzielonych kreską |, podobnie jak zapisuje się typy w PHP (np. 'int|string|bool'). Akceptowany jest również zapis nullable ?int.

Tablicę, w której wszystkie elementy są określonego typu, zapisuje się w postaci int[].

Po niektórych typach może następować dwukropek i długość :length albo zakres :[min]..[max], np. string:10 (string o długości 10 bajtów), float:10.. (liczba 10 lub większa), array:..10 (tablica o najwyżej dziesięciu elementach) albo list:10..20 (lista o 10 do 20 elementach), albo wyrażenie regularne, jak pattern:[0-9]+.

Przegląd typów i reguł:

Asercja

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

Sprawdza, czy wartość jest jednym z oczekiwanych typów oddzielonych kreską. Jeśli nie, zgłasza Nette\Utils\AssertionException. Słowo variable w komunikacie wyjątku można zastąpić parametrem $label.

Validators::assert('Nette', 'string:5'); // OK (string 'Nette' ma 5 bajtów)
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

Sprawdza, czy element o kluczu $key w tablicy $array jest jednym z oczekiwanych typów oddzielonych kreską. Jeśli nie, zgłasza Nette\Utils\AssertionException. String item '%' in array w komunikacie wyjątku można zastąpić parametrem $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.

Walidatory

is ($value, string $expected): bool

Sprawdza, czy wartość jest jednym z oczekiwanych typów oddzielonych kreską.

Validators::is(1, 'int|float');  // true
Validators::is(23, 'int:0..10'); // false (23 jest poza zakresem 0-10)
Validators::is('Nette Framework', 'string:15');     // true, długość to 15 bajtów
Validators::is('Nette Framework', 'string:8..');    // true
Validators::is('Nette Framework', 'string:30..40'); // false

everyIs (iterable $values, string $expected): bool

Sprawdza, czy każda wartość w obiekcie iterowalnym jest jednym z oczekiwanych typów oddzielonych kreską. Działa jak is() zastosowane do każdego elementu.

$list = ['Nette', 'Framework', 2020];
Validators::everyIs($list, 'string');     // false (2020 nie jest stringiem)
Validators::everyIs($list, 'string|int'); // true

isEmail (string $value): bool

Sprawdza, czy wartość jest prawidłowym adresem e-mail. Nie weryfikuje, czy domena rzeczywiście istnieje, sprawdzana jest tylko składnia. Funkcja uwzględnia również przyszłe domeny najwyższego poziomu, które mogą być również w unicode.

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

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

Sprawdza, czy wartość mieści się w podanym zakresie [min, max], przy czym górną albo dolną granicę można pominąć (null). Porównywać można liczby, stringi i obiekty DateTime.

Jeśli brakuje obu granic ([null, null]) albo wartością jest null, zwraca false.

Validators::isInRange(5, [0, 5]);     // true
Validators::isInRange(23, [null, 5]); // false
Validators::isInRange(23, [5]);       // true (odpowiednik [5, null])
Validators::isInRange(1, [5]);        // false

isNone (mixed $value): bool

Sprawdza, czy wartością jest 0, '', false, null, 0.0 albo [].

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

isNumeric (mixed $value): bool

Sprawdza, czy wartością jest liczba albo liczba zapisana jako string.

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 (zapis naukowy nie jest akceptowany)

isNumericInt (mixed $value): bool

Sprawdza, czy wartością jest liczba całkowita albo liczba całkowita zapisana jako string.

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

Sprawdza, czy wartość jest składniowo prawidłowym identyfikatorem w PHP (np. dla nazw klas, metod, funkcji itd.).

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

isBuiltinType (string $type): bool

Ustala, czy $type jest typem wbudowanym w PHP (np. string, int, array, bool). W przeciwnym razie zakłada, że jest to nazwa klasy.

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

isTypeDeclaration (string $type): bool

Sprawdza, czy podany string z deklaracją typu jest składniowo prawidłowy według reguł deklaracji typów PHP (łącznie z typami sumarycznymi, przecięciowymi i DNF).

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

Ustala, czy $name jest jednym z wewnętrznych słów kluczowych typów self, parent albo static.

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

isUnicode (mixed $value): bool

Sprawdza, czy wartość jest prawidłowym stringiem UTF-8.

Validators::isUnicode('nette'); // true
Validators::isUnicode('');      // true
Validators::isUnicode("\xA0");  // false (nieprawidłowa sekwencja UTF-8)

isUrl (string $value): bool

Sprawdza, czy wartość jest prawidłowym bezwzględnym adresem URL zgodnym z 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 (część userinfo nie jest walidowana przez tę funkcję)
Validators::isUrl('nette.org');                   // false (brak schematu)

isUri (string $value): bool

Sprawdza, czy wartość jest prawidłowym adresem URI, czyli stringiem zaczynającym się od składniowo prawidłowego schematu, po którym następuje dwukropek (np. http:, https:, mailto:, ftp:).

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