Értékellenőrzők
***************

.[perex]
Gyorsan és egyszerűen szeretné ellenőrizni, hogy egy változó tartalmaz-e például érvényes e-mail címet? Akkor jól fog jönni a [api:Nette\Utils\Validators], egy statikus osztály, amely hasznos függvényeket tartalmaz az értékek érvényesítéséhez.


Telepítés:

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

Minden példa feltételezi, hogy a következő osztály alias van definiálva:

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


Alapvető használat .[#toc-basic-usage]
======================================

A `Validators` osztály számos módszerrel rendelkezik az értékek érvényesítésére, mint például az [isList() |#isList()], [isUnicode() |#isUnicode()], [isEmail() |#isEmail()], [isUrl() |#isUrl()], stb., amelyeket a kódodban használhatsz:

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

Továbbá képes ellenőrizni, hogy az érték megfelel-e az úgynevezett [elvárt típusoknak |#expected types], ami egy olyan karakterlánc, amelyben az egyes opciókat függőleges vonallal `|` választják el. Ez megkönnyíti az unió típusok ellenőrzését az [if() |#if()] segítségével:

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

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

Olyan [állítást |#assert] is deklarálhatsz, ami kivételt dob, ha nem teljesül.


Várható típusok .[#toc-expected-types]
======================================

Az elvárt típusok egy vagy több, függőleges vonallal elválasztott változatból álló karakterlánc `|`, similar to writing types in PHP (ie. `'int|string|bool')`. A nullázható jelölés is megengedett `?int`.

Egy olyan tömböt, amelynek minden eleme egy bizonyos típusba tartozik, a `int[]` formában írunk le.

Egyes típusokat kettőspont és a hossz `:length` vagy a tartomány követheti. `:[min]..[max]`, pl. `string:10` (10 bájt hosszúságú karakterlánc), `float:10..` (10-es és annál nagyobb szám), `array:..10` (legfeljebb tíz elemű tömb) vagy `list:10..20` (10-20 elemű lista), vagy egy reguláris kifejezés a következőre `pattern:[0-9]+`.

A típusok és szabályok áttekintése:

.[wide]
| PHP típusok ||
|--------------------------
| `array` .{width: 140px} | az elemek számának tartománya megadható.
| `bool` |
| `float` | értéktartományt lehet megadni.
| `int` | az érték tartománya megadható.
| `null` |
| `object` |
| `resource` |
| `scalar` | int\|float\|bool\|string
| `string` | meg lehet adni a bájtban megadott hossz tartományt.
| `callable` |
| `iterable` |
| `mixed` |
|------------------------------------------------
| pszeudotípusok ||
|------------------------------------------------
| `list` | [indexelt tömb |#isList], az elemek számának tartománya megadható.
| `none` | üres érték: `''`, `null`, `false`
| `number` | int\ |float
| `numeric` | [szám, beleértve a szöveges megjelenítést is |#isNumeric]
| `numericint`| [egész szám, beleértve a szöveges ábrázolást is |#isNumericInt].
| `unicode` | [UTF-8 karakterlánc |#isUnicode], megadható a karakterekben kifejezett hosszúság tartománya.
|------------------------------------------------
| karakterosztály (nem lehet üres karakterlánc) ||
|------------------------------------------------
| `alnum` | minden karakter alfanumerikus
| `alpha` | minden karakter betű `[A-Za-z]`
| `digit` | minden karakter számjegy
| `lower` | minden karakter kisbetűs betű `[a-z]`
| `space` | minden karakter szóköz
| `upper` | minden karakter nagybetűs betű `[A-Z]`
| `xdigit` | minden karakter hexadecimális számjegyek `[0-9A-Fa-f]`
|------------------------------------------------
| syntax validation ||
|------------------------------------------------
| `pattern` | egy reguláris kifejezés, amelynek a teljes sztringnek meg kell felelnie.
| `email` | [Email |#isEmail]
| `identifier`| [PHP azonosító |#isPhpIdentifier]
| `url` | [URL |#isUrl]
| `uri` | [URI |#isUri]
|------------------------------------------------
| környezeti érvényesítés ||
|------------------------------------------------
| `class` | létezik osztály
| `interface` | létező interfész
| `directory` | létező könyvtár
| `file` | létező fájl


Állítás .[#toc-assertion]
=========================


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

Ellenőrzi, hogy az érték a pipával elválasztott [elvárt típusokból |#expected types] áll-e. Ha nem, akkor kivételt dob [api:Nette\Utils\AssertionException]. A kivételüzenetben a `variable` szó helyettesíthető 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 `$array` tömb `$key` eleme a tömbben csővel elválasztott, [elvárt típusokból |#expected types] áll. Ha nem, akkor kivételt dob [api:Nette\Utils\AssertionException]. A kivételüzenetben szereplő `item '%' in array` karakterláncot a `$label` paraméterrel lehet helyettesíteni.

```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 .[#toc-validators]
==============================


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

Ellenőrzi, hogy az érték a pipával [elválasztott elvárt típusokból |#expected types] áll-e.

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

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 szintaxisát ellenőrzi. A funkció számol a jövőbeli [TLD-kkel |https://en.wikipedia.org/wiki/Top-level_domain] is, amelyek szintén lehetnek unicode-ban.

```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 tartományban van-e. `[min, max]`, ahol a felső vagy alsó határérték elhagyható (`null`). Számok, karakterláncok és DateTime objektumok összehasonlíthatók.

Ha mindkét határ hiányzik (`[null, null]`), vagy az érték `null`, akkor a `false` értéket adja 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`.

```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 egy szám vagy egy karakterláncba írt 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 vagy egy karakterláncba írt 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 egy szintaktikailag érvényes azonosító-e a PHP-ben, például osztályok, metódusok, függvények stb. nevei esetében.

```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` PHP beépített típus-e. Ellenkező esetben az osztály neve.

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


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

Ellenőrzi, hogy a típusdeklaráció szintaktikailag helyes-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` egyike-e a `self`, `parent`, `static` belső típusoknak.

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


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

Ellenőrzi, hogy az érték érvényes UTF-8 karakterlánc-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 valóban egy szintaktikailag érvényes sémával kezdődő karakterlánc.

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