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:
PHP Typen | |
---|---|
array |
es kann ein Bereich für die Anzahl der Elemente angegeben werden |
bool |
|
float |
es kann ein Bereich für den Wert angegeben werden |
int |
es kann ein Bereich für den Wert angegeben werden |
null |
|
object |
|
resource |
|
scalar |
int|float|bool|string |
string |
es kann ein Bereich für die Länge in Bytes angegeben werden |
callable |
|
iterable |
|
mixed |
|
Pseudo-Typen | |
list |
indexiertes Array, es kann ein Bereich für die Anzahl der Elemente angegeben werden |
none |
leerer Wert: '' , null , false |
number |
int|float |
numeric |
Zahl einschließlich Textdarstellung |
numericint |
Ganzzahl einschließlich Textdarstellung |
unicode |
UTF-8-String, es kann ein Bereich für die Länge in Zeichen angegeben werden |
Zeichenklasse (darf kein leerer String sein) | |
alnum |
alle Zeichen sind alphanumerisch |
alpha |
alle Zeichen sind Buchstaben [A-Za-z] |
digit |
alle Zeichen sind Ziffern |
lower |
alle Zeichen sind Kleinbuchstaben [a-z] |
space |
alle Zeichen sind Leerzeichen |
upper |
alle Zeichen sind Großbuchstaben [A-Z] |
xdigit |
alle Zeichen sind hexadezimale Ziffern [0-9A-Fa-f] |
Syntaxüberprüfung | |
pattern |
regulärer Ausdruck, dem der gesamte String entsprechen muss |
email |
|
identifier |
PHP-Bezeichner |
url |
URL |
uri |
URI |
Umgebungsüberprüfung | |
class |
ist eine existierende Klasse |
interface |
ist ein existierendes Interface |
directory |
ist ein existierendes Verzeichnis |
file |
ist eine existierende Datei |
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