Érték validátorok

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 Nette\Utils\Validators, egy statikus osztály hasznos függvényekkel az értékek validálásához.

Telepítés:

composer require nette/utils

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

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 isList(), isUnicode(), isEmail(), isUrl() stb., amelyeket a kódjában használhat:

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:

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:

PHP típusok
array 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
numericint egész szám, beleértve a szöveges reprezentációt
unicode UTF-8 string, 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
identifier PHP azonosító
url URL
uri URI
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

Assertion-ök

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

Ellenőrzi, hogy az érték a függőleges vonallal elválasztott várt típusok egyike-e. Ha nem, Nette\Utils\AssertionException kivételt dob. A variable szó a kivétel szövegében helyettesíthető mással 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 $key kulcs alatti elem a $array tömbben a függőleges vonallal elválasztott várt típusok egyike-e. Ha nem, 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.

$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 függőleges vonallal elválasztott várt típusok egyike-e.

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

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-kkel is, amelyek unicode-ban is lehetnek.

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

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

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 szám-e vagy stringben megadott 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-e vagy stringben megadott 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 szintaktikailag érvényes PHP azonosító-e, például osztály-, metódus-, függvénynevekhez stb.

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 beépített PHP típus-e. Ellenkező esetben osztálynév.

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

isTypeDeclaration (string $type)bool

Ellenőrzi, hogy a megadott típusdeklaráció szintaktikailag érvényes-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 a self, parent, static belső típusok egyike-e.

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

isUnicode (mixed $value)bool

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

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