Wertvalidatoren

Sie müssen schnell und einfach prüfen, ob eine Variable zum Beispiel eine gültige E-Mail-Adresse enthält? Dann kommt Ihnen Nette\Utils\Validators gelegen, eine statische Klasse mit nützlichen Funktionen zum Validieren von Werten.

Installation:

composer require nette/utils

Alle Beispiele setzen voraus, dass dieser Klassen-Alias definiert ist:

use Nette\Utils\Validators;

Grundlegende Verwendung

Die Klasse Validators bietet zahlreiche Methoden zum Prüfen von Werten, etwa isUnicode(), isEmail(), isUrl() und so weiter, zur Verwendung in Ihrem Code:

if (!Validators::isEmail($email)) {
	throw new InvalidArgumentException('Es wurde eine ungültige E-Mail-Adresse übergeben.');
}

Darüber hinaus kann sie prüfen, ob ein Wert den sogenannten erwarteten Typen entspricht. Das ist ein String, in dem die einzelnen Möglichkeiten durch einen senkrechten Strich | getrennt sind. So lassen sich mit is() leicht Union-Typen prüfen:

if (!Validators::is($val, 'int|string|bool')) {
	// Ungültigen Typ behandeln ...
}

Damit können Sie auch Systeme bauen, in denen Erwartungen als Strings notiert werden müssen (etwa in Annotationen oder Konfigurationen) und Werte anschließend dagegen validiert werden.

Sie können auch eine Assertion deklarieren, die eine Exception wirft, wenn die Erwartung nicht erfüllt ist.

Erwartete Typen

Die erwarteten Typen bilden einen String aus einer oder mehreren Varianten, die durch einen senkrechten Strich | getrennt sind, ähnlich wie Typen in PHP geschrieben werden (z. B. 'int|string|bool'). Auch die Nullable-Schreibweise ?int wird akzeptiert.

Ein Array, dessen Elemente alle einen bestimmten Typ haben, wird in der Form int[] geschrieben.

Auf manche Typen kann ein Doppelpunkt und eine Länge :length oder ein Bereich :[min]..[max] folgen, etwa string:10 (ein String mit einer Länge von 10 Bytes), float:10.. (eine Zahl größer oder gleich 10), array:..10 (ein Array mit höchstens zehn Elementen) oder list:10..20 (eine Liste mit 10 bis 20 Elementen), oder ein regulärer Ausdruck wie pattern:[0-9]+.

Übersicht der Typen und Regeln:

Assertion

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

Prüft, ob der Wert einem der durch einen senkrechten Strich getrennten erwarteten Typen entspricht. Ist das nicht der Fall, wirft die Methode eine Nette\Utils\AssertionException. Das Wort variable in der Meldung der Exception lässt sich über den Parameter $label ersetzen.

Validators::assert('Nette', 'string:5'); // OK (der String 'Nette' hat 5 Bytes)
Validators::assert('Lorem ipsum dolor sit', 'string:78');
// AssertionException: The variable expects to be string in range 78, string 'Lorem ipsum dolor sit' given.

assertField (array $array, string|int $key, ?string $expected=null, string $label="item '%' in array"): void

Prüft, ob das Element mit dem Schlüssel $key im Array $array einem der durch einen senkrechten Strich getrennten erwarteten Typen entspricht. Ist das nicht der Fall, wirft die Methode eine Nette\Utils\AssertionException. Der String item '%' in array in der Meldung der Exception lässt sich über den Parameter $label ersetzen.

$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

Prüft, ob der Wert einem der durch einen senkrechten Strich getrennten erwarteten Typen entspricht.

Validators::is(1, 'int|float');  // true
Validators::is(23, 'int:0..10'); // false (23 liegt außerhalb des Bereichs 0-10)
Validators::is('Nette Framework', 'string:15');     // true, die Länge beträgt 15 Bytes
Validators::is('Nette Framework', 'string:8..');    // true
Validators::is('Nette Framework', 'string:30..40'); // false

everyIs (iterable $values, string $expected): bool

Prüft, ob jeder Wert in der iterierbaren Struktur einem der durch einen senkrechten Strich getrennten erwarteten Typen entspricht. Es funktioniert wie is(), angewendet auf jedes Element.

$list = ['Nette', 'Framework', 2020];
Validators::everyIs($list, 'string');     // false (2020 ist kein String)
Validators::everyIs($list, 'string|int'); // true

isEmail (string $value): bool

Prüft, ob der Wert eine gültige E-Mail-Adresse ist. Ob die Domain tatsächlich existiert, wird nicht geprüft, sondern nur die Syntax. Die Funktion berücksichtigt auch künftige TLDs, die auch in Unicode vorliegen können.

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

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

Prüft, ob der Wert im angegebenen Bereich [min, max] liegt, wobei die obere oder die untere Grenze entfallen kann (null). Vergleichen lassen sich Zahlen, Strings und DateTime-Objekte.

Fehlen beide Grenzen ([null, null]) oder ist der Wert null, gibt die Methode false zurück.

Validators::isInRange(5, [0, 5]);     // true
Validators::isInRange(23, [null, 5]); // false
Validators::isInRange(23, [5]);       // true (gleichbedeutend mit [5, null])
Validators::isInRange(1, [5]);        // false

isNone (mixed $value): bool

Prüft, ob der Wert 0, '', false, null, 0.0 oder [] ist.

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

isNumeric (mixed $value): bool

Prüft, ob der Wert eine Zahl oder eine als String dargestellte 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 (die wissenschaftliche Schreibweise wird nicht akzeptiert)

isNumericInt (mixed $value): bool

Prüft, ob der Wert eine ganze Zahl oder eine als String dargestellte ganze 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

Prüft, ob der Wert ein syntaktisch gültiger Bezeichner in PHP ist (etwa für Klassennamen, Methodennamen, Funktionsnamen und so weiter).

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

isBuiltinType (string $type): bool

Ermittelt, ob $type ein in PHP eingebauter Typ ist (etwa string, int, array, bool). Andernfalls wird angenommen, dass es sich um einen Klassennamen handelt.

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

isTypeDeclaration (string $type): bool

Prüft, ob der angegebene String einer Typdeklaration nach den Regeln von PHP syntaktisch gültig ist (einschließlich Union-, Intersection- und DNF-Typen).

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 $name): bool

Ermittelt, ob $name eines der internen Typschlüsselwörter self, parent oder static ist.

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

isUnicode (mixed $value): bool

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

Validators::isUnicode('nette'); // true
Validators::isUnicode('');      // true
Validators::isUnicode("\xA0");  // false (ungültige UTF-8-Sequenz)

isUrl (string $value): bool

Prüft, ob der Wert eine gültige absolute URL-Adresse nach RFC 3986 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 (der Teil userinfo wird von dieser Funktion nicht validiert)
Validators::isUrl('nette.org');                   // false (das Schema fehlt)

isUri (string $value): bool

Prüft, ob der Wert eine gültige URI-Adresse ist, also ein String, der mit einem syntaktisch gültigen Schema samt Doppelpunkt beginnt (etwa http:, https:, mailto:, ftp:).

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