Preverjevalniki vrednosti
*************************

.[perex]
Potrebujete hitro in preprosto preveriti, ali spremenljivka vsebuje na primer veljaven e-poštni naslov? Potem vam bo prišel prav [api:Nette\Utils\Validators], statični razred z uporabnimi funkcijami za preverjanje vrednosti.


Namestitev:

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

Vsi primeri predpostavljajo, da je definiran naslednji vzdevek razreda:

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


Osnovna uporaba .[#toc-basic-usage]
===================================

Razred `Validators` ima številne metode za preverjanje vrednosti, kot so [isList() |#isList()], [isUnicode() |#isUnicode()], [isEmail( |#isEmail()]), [isUrl() |#isUrl()] itd., ki jih lahko uporabite v svoji kodi:

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

Poleg tega lahko preveri, ali vrednost ustreza tako imenovanim [pričakovanim tipom |#expected types], kar je niz, v katerem so posamezne možnosti ločene z navpično črto `|`. Tako je preverjanje tipov zvez enostavno z uporabo [funkcije if() |#if()]:

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

Prav tako pa vam omogoča, da ustvarite sistem, v katerem je treba pričakovanja zapisati kot nize (na primer v anotacijah ali konfiguraciji) in nato preverjati v skladu z njimi.

Prav tako lahko razglasite [trditev, |#assert] ki vrže izjemo, če ni izpolnjena.


Pričakovani tipi .[#toc-expected-types]
=======================================

Pričakovani tipi so niz, sestavljen iz ene ali več različic, ločenih z navpično črto `|`, similar to writing types in PHP (ie. `'int|string|bool')`. Dovoljen je tudi ničelni zapis `?int`.

Polje, kjer so vsi elementi določenega tipa, se zapiše v obliki `int[]`.

Nekaterim tipom lahko sledita dvopičje in dolžina `:length` ali razpon `:[min]..[max]`npr. `string:10` (niz z dolžino 10 bajtov), `float:10..` (število 10 in večje), `array:..10` (polje z do desetimi elementi) ali `list:10..20` (seznam z 10 do 20 elementi), ali regularni izraz za `pattern:[0-9]+`.

Pregled vrst in pravil:

.[wide]
| Tipi PHP ||
|--------------------------
| `array` .{width: 140px} | podano je lahko območje števila elementov
| `bool` |
| `float` | obseg za vrednost je lahko podan
| `int` | lahko se navede razpon vrednosti
| `null` |
| `object` |
| `resource` |
| `scalar` | int\|float\|bool\|string
| `string` | lahko se navede razpon za dolžino v bajtih
| `callable` |
| `iterable` |
| `mixed` |
|------------------------------------------------
| psevdotipi ||
|------------------------------------------------
| `list` | [indeksirano polje |#isList], podan je lahko razpon števila elementov
| `none` | prazna vrednost: `''`, `null`, `false`
| `number` | int\|float
| `numeric` | [število, vključno z besedilno predstavitvijo |#isNumeric]
| `numericint`| [celo število, vključno z besedilno predstavitvijo |#isNumericInt]
| `unicode` | [UTF-8 niz |#isUnicode], podan je lahko razpon dolžine v znakih
|------------------------------------------------
| razred znakov (ne more biti prazen niz) ||
|------------------------------------------------
| `alnum` | vsi znaki so alfanumerični
| `alpha` | vsi znaki so črke `[A-Za-z]`
| `digit` | vsi znaki so številke
| `lower` | vsi znaki so male črke `[a-z]`
| `space` | vsi znaki so presledki
| `upper` | vsi znaki so velike črke `[A-Z]`
| `xdigit` | vsi znaki so šestnajstiške številke `[0-9A-Fa-f]`
|------------------------------------------------
| preverjanje skladnje ||
|------------------------------------------------
| `pattern` | regularni izraz, ki mu mora ustrezati celoten** niz
| `email` | [Elektronska pošta |#isEmail]
| `identifier`| [PHP identifikator |#isPhpIdentifier]
| `url` | [URL |#isUrl]
| `uri` | [URI |#isUri]
|------------------------------------------------
| potrditev okolja ||
|------------------------------------------------
| `class` | je obstoječi razred
| `interface` | je obstoječi vmesnik
| `directory` | je obstoječi imenik
| `file` | je obstoječa datoteka


Trditev .[#toc-assertion]
=========================


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

Preveri, ali je vrednost sestavljena iz [pričakovanih tipov |#expected types], ločenih s cevjo. V nasprotnem primeru vrže izjemo [api:Nette\Utils\AssertionException]. Besedo `variable` v sporočilu o izjemi lahko nadomestite s parametrom `$label`.

```php
Validators::assert('Nette', 'string:5'); // V REDU
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]
-------------------------------------------------------------------------------------------------------

Preveri, ali je element `$key` v polju `$array` iz [pričakovanih tipov |#expected types], ločenih s cevjo. V nasprotnem primeru vrže izjemo [api:Nette\Utils\AssertionException]. Niz `item '%' in array` v sporočilu o izjemi je mogoče nadomestiti s parametrom `$label`.

```php
$arr = ['foo' => 'Nette'];

Validators::assertField($arr, 'foo', 'string:5'); // V REDU
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.
```


Validatorji .[#toc-validators]
==============================


is($value, string $expected): bool .[method]
--------------------------------------------

Preveri, ali je vrednost iz [pričakovanih tipov, |#expected types] ločenih s cevjo.

```php
Validators::is(1, 'int|float');  // true
Validators::is(23, 'int:0..10'); // false
Validators::is('Nette Framework', 'string:15');     // true, length is 15 bytes
Validators::is('Nette Framework', 'string:8..');    // true
Validators::is('Nette Framework', 'string:30..40'); // false
```


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

Preveri, ali je vrednost veljaven e-poštni naslov. Ne preveri, ali domena dejansko obstaja, preveri se le sintaksa. Funkcija računa tudi na prihodnje [vrhnje domene, |https://en.wikipedia.org/wiki/Top-level_domain] ki so lahko tudi v enokodni obliki.

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


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

Preveri, ali je vrednost v danem območju `[min, max]`, pri čemer se lahko zgornja ali spodnja meja izpusti (`null`). Primerjajo se lahko številke, nizi in objekti DateTime.

Če manjkata obe meji (`[null, null]`) ali je vrednost `null`, vrne `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]
------------------------------------

Preveri, ali je vrednost `0`, `''`, `false` ali `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]
---------------------------------------

Preveri, ali je vrednost število ali število, zapisano v nizu.

```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]
------------------------------------------

Preveri, ali je vrednost celo število ali celo število, zapisano v nizu.

```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]
----------------------------------------------

Preveri, ali je vrednost sintaktično veljaven identifikator v PHP, na primer za imena razredov, metod, funkcij itd.

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


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

Ugotovi, ali je `$type` vgrajeni tip PHP. V nasprotnem primeru je ime razreda.

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


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

Preveri, ali je deklaracija tipa skladenjsko pravilna.

```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]
--------------------------------------------

Določi, ali je `$type` eden od notranjih tipov `self`, `parent`, `static`.

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


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

Preveri, ali je vrednost veljavni niz UTF-8.

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


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

Preveri, ali je vrednost veljaven naslov 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]
------------------------------------

Preveri, ali je vrednost veljaven naslov URI, torej dejansko niz, ki se začne s sintaktično veljavno shemo.

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