Wert-Validatoren

Müssen Sie schnell und einfach überprüfen, ob eine Variable z.B. eine gültige Email-Adresse enthält? Dann ist Nette\Utils\Validators genau das Richtige, eine statische Klasse mit nützlichen Funktionen zur Überprüfung von Werten.

Installation:

composer require nette/utils

Alle Beispiele gehen davon aus, dass der folgende Klassenalias definiert ist:

use Nette\Utils\Validators;

Grundlegende Verwendung

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

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

Darüber hinaus kann überprüft werden, ob der Wert die so genannten erwarteten Typen erfüllt, d. h. eine Zeichenkette, bei der die einzelnen Optionen durch einen vertikalen Balken | getrennt sind. Dies macht es einfach, Union-Typen mit if() zu überprüfen:

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

Es gibt Ihnen aber auch die Möglichkeit, ein System zu erstellen, bei dem es notwendig ist, Erwartungen als Zeichenketten zu schreiben (z. B. in Anmerkungen oder in der Konfiguration) und dann anhand dieser zu überprüfen.

Sie können auch eine Behauptung deklarieren, die eine Ausnahme auslöst, wenn sie nicht erfüllt ist.

Erwartete Typen

Ein erwarteter Typ ist eine Zeichenkette, die aus einer oder mehreren Varianten besteht, die durch einen senkrechten Strich getrennt sind |, similar to writing types in PHP (ie. 'int|string|bool'). Die Notation mit Nullen ist ebenfalls zulässig ?int.

Ein Array, bei dem alle Elemente von einem bestimmten Typ sind, wird in der Form int[] geschrieben.

Einige Typen können von einem Doppelpunkt gefolgt werden und die Länge :length oder der Bereich :[min]..[max]folgen, z.B. string:10 (ein String mit einer Länge von 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 für pattern:[0-9]+.

Übersicht über die Typen und Regeln:

Behauptung

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

Überprüft, ob der Wert den erwarteten, durch Pipe getrennten Typen entspricht. Wenn nicht, wird die Ausnahme Nette\Utils\AssertionException ausgelöst. Das Wort variable in der Ausnahmemeldung kann durch den Parameter $label 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 $key im Array $array die erwarteten, durch Pipe getrennten Typen enthält. Wenn nicht, wird die Ausnahme Nette\Utils\AssertionException ausgelöst. Die Zeichenkette item '%' in array in der Ausnahmemeldung kann durch den Parameter $label 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.

Prüfer

is ($value, string $expected): bool

Prüft, ob der Wert die erwarteten, durch Pipe getrennten Typen enthält.

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

Überprüft, ob der Wert eine gültige E-Mail-Adresse ist. Es wird nicht überprüft, ob die Domäne tatsächlich existiert, nur die Syntax wird überprüft. Die Funktion rechnet auch mit zukünftigen 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

Prüft, ob der Wert innerhalb des angegebenen Bereichs liegt [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

Prüft, ob der Wert eine Zahl oder eine in eine Zeichenkette 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

Prüft, ob der Wert eine Ganzzahl oder eine in eine Zeichenkette geschriebene Ganzzahl 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, zum Beispiel für Namen von Klassen, Methoden, Funktionen usw.

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. Andernfalls ist es der Klassenname.

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

isTypeDeclaration (string $type): bool

Prüft, ob die Typdeklaration syntaktisch korrekt 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

Ermittelt, 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 eine gültige UTF-8-Zeichenkette ist.

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

isUrl (mixed $value): bool

Prü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, d. h. tatsächlich eine Zeichenfolge, die 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