Érték validátorok
*****************

.[perex]
Gyorsan és egyszerűen kell ellenőriznie, hogy egy változóban például érvényes e-mail cím van-e? Ehhez hasznos lesz a [api:Nette\Utils\Validators], egy statikus osztály hasznos függvényekkel az értékek validálásához.


Telepítés:

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

Minden példa feltételezi a létrehozott aliast:

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


Alapvető használat
==================

Az osztály számos metódussal rendelkezik az értékek ellenőrzésére, mint például a [#isUnicode()], [#isEmail()], [#isUrl()] stb., amelyeket a kódjában használhat:

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

Továbbá képes ellenőrizni, hogy az érték ún. [#várt típusok]-e, ami egy string, ahol az egyes lehetőségeket függőleges vonal `|` választja el. Így könnyen ellenőrizhetünk több típust a [#is()] segítségével:

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

De ez lehetőséget ad arra is, hogy olyan rendszert hozzunk létre, ahol az elvárásokat stringként kell megadni (például annotációkban vagy konfigurációban), majd ezek alapján ellenőrizni az értékeket.

A várt típusokra követelményt is állíthatunk a [#assert()] segítségével, amely ha nem teljesül, kivételt dob.


Várt típusok
============

A várt típusok egy stringet alkotnak, amely egy vagy több, függőleges vonallal `|` elválasztott változatból áll, hasonlóan ahhoz, ahogy a típusokat PHP-ban írják (pl. `'int|string|bool'`). Elfogadott a nullable jelölés `?int` is.

Egy tömb, ahol minden elem egy bizonyos típusú, `int[]` formában íródik.

Néhány típus után kettőspont és hossz `:length` vagy tartomány `:[min]..[max]` következhet, pl. `string:10` (10 bájt hosszúságú string), `float:10..` (10-es vagy nagyobb szám), `array:..10` (legfeljebb tíz elemű tömb) vagy `list:10..20` (10-20 elemű lista), illetve reguláris kifejezés a `pattern:[0-9]+` esetén.

Típusok és szabályok áttekintése:

.[wide]
| PHP típusok   ||
|--------------------------
| `array` .{width: 140px} | megadható tartomány az elemek számára
| `bool`     |
| `float`    | megadható tartomány az értékre
| `int`      | megadható tartomány az értékre
| `null`     |
| `object`   |
| `resource` |
| `scalar`   | int\|float\|bool\|string
| `string`   | megadható tartomány a hosszra bájtokban
| `callable` |
| `iterable` |
| `mixed`    |
|--------------------------
| pszeudo-típusok ||
|------------------------------------------------
| `list`      | indexelt tömb, megadható tartomány az elemek számára
| `none`      | üres érték: `''`, `null`, `false`
| `number`    | int\|float
| `numeric`   | [szám, beleértve a szöveges reprezentációt |#isNumeric]
| `numericint`| [egész szám, beleértve a szöveges reprezentációt |#isNumericInt]
| `unicode`   | [UTF-8 string |#isUnicode], megadható tartomány a hosszra karakterekben
|--------------------------
| karakterosztály  (nem lehet üres string) ||
|------------------------------------------------
| `alnum`   | minden karakter alfanumerikus
| `alpha`   | minden karakter betű `[A-Za-z]`
| `digit`   | minden karakter számjegy
| `lower`   | minden karakter kisbetű `[a-z]`
| `space`   | minden karakter szóköz
| `upper`   | minden karakter nagybetű `[A-Z]`
| `xdigit`  | minden karakter hexadecimális számjegy `[0-9A-Fa-f]`
|--------------------------
| szintaxis ellenőrzése  ||
|------------------------------------------------
| `pattern`   | reguláris kifejezés, amelynek a **teljes** stringnek meg kell felelnie
| `email`     | [E-mail |#isEmail]
| `identifier`| [PHP azonosító |#isPhpIdentifier]
| `url`       | [URL |#isUrl]
| `uri`       | [URI |#isUri]
|--------------------------
| környezet ellenőrzése  ||
|------------------------------------------------
| `class`     | létező osztály
| `interface` | létező interfész
| `directory` | létező könyvtár
| `file`      | létező fájl


Assertok
========


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

Ellenőrzi, hogy az érték a függőleges vonallal elválasztott [#várt típusok] egyike-e. Ha nem, [api:Nette\Utils\AssertionException] kivételt dob. A `variable` szó a kivétel szövegében helyettesíthető mással a `$label` paraméterrel.

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

Ellenőrzi, hogy a `$key` kulcs alatti elem a `$array` tömbben a függőleges vonallal elválasztott [#várt típusok] egyike-e. Ha nem, [api:Nette\Utils\AssertionException] kivételt dob. Az `item '%' in array` string a kivétel szövegében helyettesíthető mással a `$label` paraméterrel.

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


Validátorok
===========


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

Ellenőrzi, hogy az érték a függőleges vonallal elválasztott [#várt típusok] egyike-e.

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


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

Ellenőrzi, hogy az érték érvényes e-mail cím-e. Nem ellenőrzi, hogy a domain valóban létezik-e, csak a szintaxist ellenőrzi. A funkció számol a jövőbeli [TLD|https://hu.wikipedia.org/wiki/Legfelső_szintű_tartomány]-kkel is, amelyek unicode-ban is lehetnek.

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


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

Ellenőrzi, hogy az érték a megadott `[min, max]` tartományban van-e, ahol a felső vagy alsó határt elhagyhatjuk (`null`). Összehasonlíthatók számok, stringek és DateTime objektumok.

Ha mindkét határ hiányzik (`[null, null]`) vagy az érték `null`, `false`-t ad vissza.

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

Ellenőrzi, hogy az érték `0`, `''`, `false` vagy `null`-e.

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

Ellenőrzi, hogy az érték szám-e vagy stringben megadott szám.

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

Ellenőrzi, hogy az érték egész szám-e vagy stringben megadott egész szám.

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

Ellenőrzi, hogy az érték szintaktikailag érvényes PHP azonosító-e, például osztály-, metódus-, függvénynevekhez stb.

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


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

Megállapítja, hogy a `$type` beépített PHP típus-e. Ellenkező esetben osztálynév.

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


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

Ellenőrzi, hogy a megadott típusdeklaráció szintaktikailag érvényes-e.

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

Megállapítja, hogy a `$type` a `self`, `parent`, `static` belső típusok egyike-e.

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


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

Ellenőrzi, hogy az érték érvényes UTF-8 string-e.

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


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

Ellenőrzi, hogy az érték érvényes URL cím-e.

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

Ellenőrzi, hogy az érték érvényes URI cím-e, azaz egy szintaktikailag érvényes sémával kezdődő string.

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