Validatori de valori
********************

.[perex]
Aveți nevoie să verificați rapid și ușor dacă o variabilă conține, de exemplu, o adresă de e-mail validă? Atunci vă va fi de folos [api:Nette\Utils\Validators], o clasă statică cu funcții utile pentru validarea valorilor.


Instalare:

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

Toate exemplele presupun că este definit următorul alias de clasă:

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


Utilizare de bază .[#toc-basic-usage]
=====================================

Clasa `Validators` are o serie de metode de validare a valorilor, cum ar fi [isList() |#isList()], [isUnicode() |#isUnicode()], [isEmail() |#isEmail()], [isUrl() |#isUrl()] etc., care pot fi utilizate în codul dumneavoastră:

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

În plus, aceasta poate verifica dacă valoarea satisface așa-numitele [tipuri așteptate |#expected types], care este un șir de caractere în care opțiunile individuale sunt separate de o bară verticală `|`. Acest lucru facilitează verificarea tipurilor de uniune folosind [if() |#if()]:

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

Dar vă oferă, de asemenea, posibilitatea de a crea un sistem în care este necesar să scrieți așteptările sub formă de șiruri de caractere (de exemplu, în adnotări sau în configurare) și apoi să verificați în funcție de acestea.

De asemenea, puteți declara o [aserțiune |#assert], care aruncă o excepție dacă nu este îndeplinită.


Tipuri de așteptări .[#toc-expected-types]
==========================================

Un tip așteptat este un șir de caractere format din una sau mai multe variante separate de o bară verticală `|`, similar to writing types in PHP (ie. `'int|string|bool')`. Este permisă, de asemenea, o notație nulă `?int`.

O matrice în care toate elementele sunt de un anumit tip se scrie sub forma `int[]`.

Unele tipuri pot fi urmate de două puncte și de lungimea `:length` sau de intervalul `:[min]..[max]`, de exemplu `string:10` (un șir de caractere cu o lungime de 10 octeți), `float:10..` (număr mai mare sau egal cu 10), `array:..10` (matrice de până la zece elemente) sau `list:10..20` (listă cu 10-20 de elemente), sau o expresie regulată pentru `pattern:[0-9]+`.

Prezentare generală a tipurilor și a regulilor:

.[wide]
| Tipuri PHP ||
|--------------------------
| `array` .{width: 140px} | se poate da un interval pentru numărul de elemente
| `bool` |
| `float` | se poate da un interval pentru valoarea
| `int` | se poate indica intervalul pentru valoarea
| `null` |
| `object` |
| `resource` |
| `scalar` | int\|float\|bool\|stringă
| `string` | se poate indica intervalul pentru lungimea în octeți
| `callable` |
| `iterable` |
| `mixed` |
|------------------------------------------------
| pseudo-tipuri ||
|------------------------------------------------
| `list` | [array indexat |#isList], se poate da un interval pentru numărul de elemente
| `none` | valoare goală: `''`, `null`, `false`
| `number` | int\|float
| `numeric` | [număr care include o reprezentare textuală |#isNumeric]
| `numericint`| [număr întreg, inclusiv reprezentare textuală |#isNumericInt]
| `unicode` | [șir UTF-8 |#isUnicode], se poate da un interval pentru lungimea în caractere
|------------------------------------------------
| clasa de caractere (nu poate fi un șir gol) ||
|------------------------------------------------
| `alnum` | toate caracterele sunt alfanumerice
| `alpha` | toate caracterele sunt litere `[A-Za-z]`
| `digit` | toate caracterele sunt cifre
| `lower` | toate caracterele sunt litere minuscule `[a-z]`
| `space` | toate caracterele sunt spații
| `upper` | toate caracterele sunt litere majuscule `[A-Z]`
| `xdigit` | toate caracterele sunt cifre hexazecimale `[0-9A-Fa-f]`
|------------------------------------------------
| validarea sintaxei ||
|------------------------------------------------
| `pattern` | o expresie regulată cu care trebuie să se potrivească **întregul** șir de caractere
| `email` | [Email |#isEmail]
| `identifier`| [Identificatorul PHP |#isPhpIdentifier]
| `url` | [URL |#isUrl]
| `uri` | [URI |#isUri]
|------------------------------------------------
| validarea mediului ||
|------------------------------------------------
| `class` | este o clasă existentă
| `interface` | este o interfață existentă
| `directory` | este un director existent
| `file` | este un fișier existent


Afirmație .[#toc-assertion]
===========================


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

Verifică dacă valoarea este de [tipurile așteptate |#expected types], separate prin pipe. În caz contrar, se aruncă o excepție [api:Nette\Utils\AssertionException]. Cuvântul `variable` din mesajul de excepție poate fi înlocuit cu parametrul `$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]
-----------------------------------------------------------------------------------------------------

Verifică dacă elementul `$key` din array-ul `$array` este format din [tipurile așteptate |#expected types], separate prin pipe. În caz contrar, se aruncă excepția [api:Nette\Utils\AssertionException]. Șirul `item '%' in array` din mesajul de excepție poate fi înlocuit cu parametrul `$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.
```


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


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

Verifică dacă valoarea este formată din [tipurile așteptate |#expected types], separate prin pipe.

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

Verifică dacă valoarea este o adresă de e-mail validă. Nu se verifică dacă domeniul există cu adevărat, ci doar sintaxa. Funcția ia în calcul și viitoarele [TLD-uri |https://en.wikipedia.org/wiki/Top-level_domain], care pot fi, de asemenea, în unicode.

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


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

Verifică dacă valoarea se află în intervalul dat `[min, max]`, unde limita superioară sau inferioară poate fi omisă (`null`). Pot fi comparate numere, șiruri de caractere și obiecte DateTime.

În cazul în care ambele limite lipsesc (`[null, null]`) sau valoarea este `null`, se returnează `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]
------------------------------------

Verifică dacă valoarea este `0`, `''`, `false` sau `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]
---------------------------------------

Verifică dacă valoarea este un număr sau un număr scris într-un șir de caractere.

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

Verifică dacă valoarea este un număr întreg sau un număr întreg scris într-un șir de caractere.

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

Verifică dacă valoarea este un identificator valid din punct de vedere sintactic în PHP, de exemplu pentru nume de clase, metode, funcții etc.

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


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

Determină dacă `$type` este un tip încorporat în PHP. În caz contrar, este numele clasei.

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


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

Verifică dacă declarația de tip este corectă din punct de vedere sintactic.

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

Determină dacă `$type` este unul dintre tipurile interne `self`, `parent`, `static`.

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


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

Verifică dacă valoarea este un șir UTF-8 valid.

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


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

Verifică dacă valoarea este o adresă URL validă.

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

Verifică dacă valoarea este o adresă URI validă, adică, de fapt, un șir care începe cu o schemă validă din punct de vedere sintactic.

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