Wertvalidatoren

Müssen Sie schnell und einfach überprüfen, ob eine Variable beispielsweise eine gültige E-Mail-Adresse enthält? Dann wird Ihnen Nette\Utils\Validators, eine statische Klasse mit nützlichen Funktionen zur Wertvalidierung, nützlich sein.

Installation:

composer require nette/utils

Alle Beispiele setzen voraus, dass ein Alias erstellt wurde:

use Nette\Utils\Validators;

Grundlegende Verwendung

Die Klasse verfügt über eine Reihe von Methoden zur Überprüfung von Werten, wie z.B. isList(), isUnicode(), isEmail(), isUrl() usw. zur Verwendung in Ihrem Code:

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

Weiterhin kann sie überprüfen, ob der Wert ein sogenannter erwarteter Typ ist, was ein String ist, bei dem die einzelnen Möglichkeiten durch einen senkrechten Strich | getrennt sind. Wir können so einfach mehrere Typen mit if() überprüfen:

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

Aber es gibt uns auch die Möglichkeit, ein System zu erstellen, bei dem Erwartungen als Strings geschrieben werden müssen (zum Beispiel in Annotationen oder Konfigurationen) und dann die Werte entsprechend überprüft werden.

Auf erwartete Typen kann auch eine Anforderung assert() gestellt werden, die, wenn sie nicht erfüllt ist, eine Ausnahme auslöst.

Erwartete Typen

Erwartete Typen bilden einen String, der aus einer oder mehreren Varianten besteht, die durch einen senkrechten Strich | getrennt sind, ähnlich wie Typen in PHP geschrieben werden (z.B. 'int|string|bool'). Die nullable Notation ?int wird ebenfalls akzeptiert.

Arrays, bei denen alle Elemente eines bestimmten Typs sind, werden im Format int[] geschrieben.

Hinter einigen Typen kann ein Doppelpunkt und eine Länge :length oder ein Bereich :[min]..[max] folgen, z.B. string:10 (String der Länge 10 Bytes), float:10.. (Zahl 10 und größer), array:..10 (Array mit bis zu zehn Elementen) oder list:10..20 (Liste mit 10 bis 20 Elementen), oder ein regulärer Ausdruck bei pattern:[0-9]+.

Übersicht der Typen und Regeln:

Assertion

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

Überprüft, ob der Wert einer der erwarteten Typen ist, die durch einen senkrechten Strich getrennt sind. Wenn nicht, wird eine Ausnahme Nette\Utils\AssertionException geworfen. Das Wort variable im Ausnahmetext kann durch den Parameter $label durch ein anderes ersetzt werden.

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

Überprüft, ob das Element unter dem Schlüssel $key im Array $array einer der erwarteten Typen ist, die durch einen senkrechten Strich getrennt sind. Wenn nicht, wird eine Ausnahme Nette\Utils\AssertionException geworfen. Der String item '%' in array im Ausnahmetext kann durch den Parameter $label durch einen anderen ersetzt werden.

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

Validatoren

is ($value, string $expected): bool

Überprüft, ob der Wert einer der erwarteten Typen ist, die durch einen senkrechten Strich getrennt sind.

Validators::is(1, 'int|float');  // true
Validators::is(23, 'int:0..10'); // false
Validators::is('Nette Framework', 'string:15');     // true, Länge ist 15 Bytes
Validators::is('Nette Framework', 'string:8..');    // true
Validators::is('Nette Framework', 'string:30..40'); // false

isEmail (mixed $value): bool

Überprüft, ob der Wert eine gültige E-Mail-Adresse ist. Es wird nicht überprüft, ob die Domain tatsächlich existiert, nur die Syntax wird überprüft. Die Funktion berücksichtigt auch zukünftige TLDs, die auch in Unicode sein können.

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

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

Überprüft, ob der Wert im angegebenen Bereich [min, max] liegt, wobei die obere oder untere Grenze weggelassen werden kann (null). Es können Zahlen, Strings und DateTime-Objekte verglichen werden.

Wenn beide Grenzen fehlen ([null, null]) oder der Wert null ist, wird false zurückgegeben.

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

Überprüft, ob der Wert 0, '', false oder null ist.

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

isNumeric (mixed $value): bool

Überprüft, ob der Wert eine Zahl oder eine in einem String geschriebene Zahl ist.

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

Überprüft, ob der Wert eine ganze Zahl oder eine in einem String geschriebene Zahl ist.

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

Überprüft, ob der Wert ein syntaktisch gültiger Bezeichner in PHP ist, zum Beispiel für Klassen-, Methoden-, Funktionsnamen usw.

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

isBuiltinType (string $type): bool

Stellt fest, ob $type ein eingebauter PHP-Typ ist. Andernfalls handelt es sich um einen Klassennamen.

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

isTypeDeclaration (string $type): bool

Überprüft, ob die angegebene Typdeklaration syntaktisch gültig ist.

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

Stellt fest, ob $type einer der internen Typen self, parent, static ist.

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

isUnicode (mixed $value): bool

Überprüft, ob der Wert ein gültiger UTF-8-String ist.

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

isUrl (mixed $value): bool

Überprüft, ob der Wert eine gültige URL-Adresse ist.

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

Überprüft, ob der Wert eine gültige URI-Adresse ist, also eigentlich ein String, der mit einem syntaktisch gültigen Schema beginnt.

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