Értékellenőrzők

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 Nette\Utils\Validators, egy statikus osztály, amely hasznos függvényeket tartalmaz az értékek érvényesítéséhez.

Telepítés:

composer require nette/utils

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

use Nette\Utils\Validators;

Alapvető használat

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

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, 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() segítségével:

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 is deklarálhatsz, ami kivételt dob, ha nem teljesül.

Várható típusok

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:

Állítás

assert($value, string $expected, string $label='variable'): void

Ellenőrzi, hogy az érték a pipával elválasztott elvárt típusokból áll-e. Ha nem, akkor kivételt dob Nette\Utils\AssertionException. A kivételüzenetben a variable szó helyettesíthető a $label paraméterrel.

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

Ellenőrzi, hogy a $array tömb $key eleme a tömbben csővel elválasztott, elvárt típusokból áll. Ha nem, akkor kivételt dob Nette\Utils\AssertionException. A kivételüzenetben szereplő item '%' in array karakterláncot a $label paraméterrel lehet helyettesíteni.

$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

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

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

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 is, amelyek szintén lehetnek unicode-ban.

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

isInRange(mixed $value, array $range): bool

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.

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

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

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

isNumeric(mixed $value): bool

Ellenőrzi, hogy az érték egy szám vagy egy karakterláncba írt szám.

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

Ellenőrzi, hogy az érték egész szám vagy egy karakterláncba írt egész szám.

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

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.

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

isBuiltinType(string $type): bool

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

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

isTypeDeclaration(string $type): bool

Ellenőrzi, hogy a típusdeklaráció szintaktikailag helyes-e.

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

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

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

isUnicode(mixed $value): bool

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

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

isUrl(mixed $value): bool

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

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

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.

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