Walidatory wartości
*******************

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


Instalacja:

```shell
composer require nette/utils
```

Wszystkie przykłady zakładają utworzenie aliasu:

```php
use Nette\Utils\Validators;
```


Podstawowe użycie
=================

Klasa dysponuje szeregiem metod do kontroli wartości, takich jak [#isUnicode], [#isEmail], [#isUrl] itp., do wykorzystania w Twoim kodzie:

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

Ponadto potrafi zweryfikować, czy wartość jest tzw. [oczekiwanym typem |#Oczekiwane typy], czyli ciągiem znaków, gdzie poszczególne opcje oddziela się pionową kreską `|`. Możemy więc łatwo zweryfikować wiele typów za pomocą [#is()]:

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

Ale daje nam to również możliwość stworzenia systemu, w którym oczekiwania muszą być zapisywane jako ciągi znaków (na przykład w adnotacjach lub konfiguracji), a następnie według nich weryfikować wartości.

Na oczekiwane typy można również nałożyć wymaganie [##assert()], które, jeśli nie zostanie spełnione, zgłosi wyjątek.


Oczekiwane typy
===============

Oczekiwane typy tworzą ciąg znaków składający się z jednej lub więcej wariantów oddzielonych pionową kreską `|`, podobnie jak zapisuje się typy w PHP (np. `'int|string|bool'`). Akceptowany jest również zapis nullable `?int`.

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

Za niektórymi typami może następować dwukropek i długość `:length` lub zakres `:[min]..[max]`, np. `string:10` (ciąg o długości 10 bajtów), `float:10..` (liczba 10 i większa), `array:..10` (tablica do dziesięciu elementów) lub `list:10..20` (lista z 10 do 20 elementami), ewentualnie wyrażenie regularne przy `pattern:[0-9]+`.

Przegląd typów i reguł:

.[wide]
| Typy PHP   ||
|--------------------------
| `array` .{width: 140px} | można podać zakres liczby elementów
| `bool`     |
| `float`    | można podać zakres wartości
| `int`      | można podać zakres wartości
| `null`     |
| `object`   |
| `resource` |
| `scalar`   | int\|float\|bool\|string
| `string`   | można podać zakres długości w bajtach
| `callable` |
| `iterable` |
| `mixed`    |
|--------------------------
| pseudo-typy ||
|------------------------------------------------
| `list`      | tablica indeksowana, można podać zakres liczby elementów
| `none`      | pusta wartość: `''`, `null`, `false`
| `number`    | int\|float
| `numeric`   | [liczba wraz z reprezentacją tekstową |#isNumeric]
| `numericint`| [liczba całkowita wraz z reprezentacją tekstową |#isNumericInt]
| `unicode`   | [ciąg UTF-8 |#isUnicode], można podać zakres długości w znakach
|--------------------------
| klasa znaków (nie może być pustym ciągiem) ||
|------------------------------------------------
| `alnum`   | wszystkie znaki są alfanumeryczne
| `alpha`   | wszystkie znaki są literami `[A-Za-z]`
| `digit`   | wszystkie znaki są cyframi
| `lower`   | wszystkie znaki są małymi literami `[a-z]`
| `space`   | wszystkie znaki są spacjami
| `upper`   | wszystkie znaki są wielkimi literami `[A-Z]`
| `xdigit`  | wszystkie znaki są cyframi szesnastkowymi `[0-9A-Fa-f]`
|--------------------------
| weryfikacja składni  ||
|------------------------------------------------
| `pattern`   | wyrażenie regularne, któremu musi odpowiadać **cały** ciąg
| `email`     | [E-mail |#isEmail]
| `identifier`| [Identyfikator PHP |#isPhpIdentifier]
| `url`       | [URL |#isUrl]
| `uri`       | [URI |#isUri]
|--------------------------
| weryfikacja środowiska  ||
|------------------------------------------------
| `class`     | jest istniejącą klasą
| `interface` | jest istniejącym interfejsem
| `directory` | jest istniejącym katalogiem
| `file`      | jest istniejącym plikiem


Asercje
=======


assert($value, string $expected, string $label='variable'): void .[method]
--------------------------------------------------------------------------

Sprawdza, czy wartość jest jednym z [oczekiwanych typów |#Oczekiwane typy] oddzielonych pionową kreską. Jeśli nie, zgłasza wyjątek [api:Nette\Utils\AssertionException]. Słowo `variable` w tekście wyjątku można zastąpić innym za pomocą parametru `$label`.

```php
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 .[method]
-------------------------------------------------------------------------------------------------------

Sprawdza, czy element pod kluczem `$key` w tablicy `$array` jest jednym z [oczekiwanych typów |#Oczekiwane typy] oddzielonych pionową kreską. Jeśli nie, zgłasza wyjątek [api:Nette\Utils\AssertionException]. Ciąg `item '%' in array` w tekście wyjątku można zastąpić innym za pomocą parametru `$label`.

```php
$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 .[method]
--------------------------------------------

Sprawdza, czy wartość jest jednym z [oczekiwanych typów |#Oczekiwane typy] oddzielonych pionową kreską.

```php
Validators::is(1, 'int|float');  // true
Validators::is(23, 'int:0..10'); // false
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
```


isEmail(mixed $value): bool .[method]
-------------------------------------

Sprawdza, czy wartość jest prawidłowym adresem e-mail. Nie sprawdza, czy domena faktycznie istnieje, weryfikowana jest tylko składnia. Funkcja uwzględnia również przyszłe [TLD|https://pl.wikipedia.org/wiki/Domena_najwyższego_poziomu], które mogą być również w unicode.

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


isInRange(mixed $value, array $range): bool .[method]
-----------------------------------------------------

Sprawdza, czy wartość znajduje się w danym zakresie `[min, max]`, gdzie górną lub dolną granicę można pominąć (`null`). Można porównywać liczby, ciągi znaków i obiekty DateTime.

Jeśli brakuje obu granic (`[null, null]`) lub wartość jest `null`, zwraca `false`.

```php
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 .[method]
------------------------------------

Sprawdza, czy wartość to `0`, `''`, `false` lub `null`.

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


isNumeric(mixed $value): bool .[method]
---------------------------------------

Sprawdza, czy wartość jest liczbą lub liczbą zapisaną w ciągu znaków.

```php
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 .[method]
------------------------------------------

Sprawdza, czy wartość jest liczbą całkowitą lub liczbą całkowitą zapisaną w ciągu znaków.

```php
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 .[method]
----------------------------------------------

Sprawdza, czy wartość jest składniowo poprawnym identyfikatorem w PHP, na przykład dla nazw klas, metod, funkcji itp.

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


isBuiltinType(string $type): bool .[method]
-------------------------------------------

Sprawdza, czy `$type` jest wbudowanym typem PHP. W przeciwnym razie jest to nazwa klasy.

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


isTypeDeclaration(string $type): bool .[method]
-----------------------------------------------

Sprawdza, czy podana deklaracja typu jest składniowo poprawna.

```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 $type): bool .[method]
--------------------------------------------

Sprawdza, czy `$type` jest jednym z wewnętrznych typów `self`, `parent`, `static`.

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


isUnicode(mixed $value): bool .[method]
---------------------------------------

Sprawdza, czy wartość jest prawidłowym ciągiem UTF-8.

```php
Validators::isUnicode('nette'); // true
Validators::isUnicode('');      // true
Validators::isUnicode("\xA0");  // false
```


isUrl(mixed $value): bool .[method]
-----------------------------------

Sprawdza, czy wartość jest prawidłowym adresem URL.

```php
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 .[method]
------------------------------------

Sprawdza, czy wartość jest prawidłowym adresem URI, czyli właściwie ciągiem zaczynającym się od składniowo poprawnego schematu.

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