Nette Documentation Preview

syntax
Wert-Validatoren
****************

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


Installation:

```shell
composer require nette/utils
```

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

```php
use Nette\Utils\Validators;
```


Grundlegende Verwendung .[#toc-basic-usage]
===========================================

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

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

Darüber hinaus kann überprüft werden, ob der Wert die so genannten [erwarteten Typen |#expected types] 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() |#if()] zu überprüfen:

```php
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 |#assert] deklarieren, die eine Ausnahme auslöst, wenn sie nicht erfüllt ist.


Erwartete Typen .[#toc-expected-types]
======================================

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:

.[wide]
| PHP-Typen ||
|--------------------------
| `array` .{width: 140px} | Bereich für die Anzahl der Elemente kann angegeben werden
| `bool` |
| `float` | Bereich für den Wert kann angegeben werden
| `int` | Bereich für den Wert kann angegeben werden
| `null` |
| `object` |
| `resource` |
| `scalar` | int\|float\|bool\|string
| `string` | Bereich für die Länge in Bytes kann angegeben werden
| `callable` |
| `iterable` |
| `mixed` |
|------------------------------------------------
| pseudo-types ||
|------------------------------------------------
| `list` | [indiziertes Array |#isList], Bereich für die Anzahl der Elemente kann angegeben werden
| `none` | leerer Wert: `''`, `null`, `false`
| `number` | int\|Float
| `numeric` | [Zahl mit Textdarstellung |#isNumeric]
| `numericint`| [Ganzzahl mit Textdarstellung|#isNumericInt]
| `unicode` | [UTF-8 string |#isUnicode], Bereich für die Länge in Zeichen kann angegeben werden
|------------------------------------------------
| Zeichenklasse (kann keine leere Zeichenkette 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 Hexadezimalziffern `[0-9A-Fa-f]`
|------------------------------------------------
| Syntaxprüfung ||
|------------------------------------------------
| `pattern` | ein regulärer Ausdruck, dem die **gesamte** Zeichenkette entsprechen muss
| `email` | [E-Mail |#isEmail]
| `identifier`| [PHP-Bezeichner |#isPhpIdentifier]
| `url` | [URL |#isUrl]
| `uri` | [URI |#isUri]
|------------------------------------------------
| Umgebungsvalidierung ||
|------------------------------------------------
| `class` | ist vorhandene Klasse
| `interface` | ist existierende Schnittstelle
| `directory` | ist ein vorhandenes Verzeichnis
| `file` | ist existierende Datei


Behauptung .[#toc-assertion]
============================


assert($value, string $expected, string $label='variable'): void .[method]
--------------------------------------------------------------------------

Überprüft, ob der Wert den [erwarteten |#expected types], durch Pipe getrennten [Typen |#expected types] entspricht. Wenn nicht, wird die Ausnahme [api:Nette\Utils\AssertionException] ausgelöst. Das Wort `variable` in der Ausnahmemeldung kann durch den Parameter `$label` ersetzt werden.

```php
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 .[method]
-----------------------------------------------------------------------------------------------------

Überprüft, ob das Element `$key` im Array `$array` die [erwarteten |#expected types], durch Pipe getrennten [Typen |#expected types] enthält. Wenn nicht, wird die Ausnahme [api:Nette\Utils\AssertionException] ausgelöst. Die Zeichenkette `item '%' in array` in der Ausnahmemeldung kann durch den Parameter `$label` ersetzt werden.

```php
$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 .[#toc-validators]
=========================


is($value, string $expected): bool .[method]
--------------------------------------------

Prüft, ob der Wert die [erwarteten |#expected types], durch Pipe getrennten [Typen |#expected types] enthält.

```php
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 .[method]
-------------------------------------

Ü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 |https://en.wikipedia.org/wiki/Top-level_domain], die auch in Unicode sein können.

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


isInRange(mixed $value, array $range): bool .[method]
-----------------------------------------------------

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.

```php
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 .[method]
------------------------------------

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

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


isNumeric(mixed $value): bool .[method]
---------------------------------------

Prüft, ob der Wert eine Zahl oder eine in eine Zeichenkette geschriebene Zahl ist.

```php
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 .[method]
------------------------------------------

Prüft, ob der Wert eine Ganzzahl oder eine in eine Zeichenkette geschriebene Ganzzahl ist.

```php
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 .[method]
----------------------------------------------

Prüft, ob der Wert ein syntaktisch gültiger Bezeichner in PHP ist, zum Beispiel für Namen von Klassen, Methoden, Funktionen usw.

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


isBuiltinType(string $type): bool .[method]
-------------------------------------------

Ermittelt, ob `$type` ein in PHP eingebauter Typ ist. Andernfalls ist es der Klassenname.

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


isTypeDeclaration(string $type): bool .[method]
-----------------------------------------------

Prüft, ob die Typdeklaration syntaktisch korrekt ist.

```php
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 .[method]
--------------------------------------------

Ermittelt, ob `$type` einer der internen Typen `self`, `parent`, `static` ist.

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


isUnicode(mixed $value): bool .[method]
---------------------------------------

Überprüft, ob der Wert eine gültige UTF-8-Zeichenkette ist.

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


isUrl(mixed $value): bool .[method]
-----------------------------------

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

```php
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 .[method]
------------------------------------

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

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

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:

PHP-Typen
array Bereich für die Anzahl der Elemente kann angegeben werden
bool  
float Bereich für den Wert kann angegeben werden
int Bereich für den Wert kann angegeben werden
null  
object  
resource  
scalar int|float|bool|string
string Bereich für die Länge in Bytes kann angegeben werden
callable  
iterable  
mixed  
pseudo-types
list indiziertes Array, Bereich für die Anzahl der Elemente kann angegeben werden
none leerer Wert: '', null, false
number int|Float
numeric Zahl mit Textdarstellung
numericint Ganzzahl mit Textdarstellung
unicode UTF-8 string, Bereich für die Länge in Zeichen kann angegeben werden
Zeichenklasse (kann keine leere Zeichenkette 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 Hexadezimalziffern [0-9A-Fa-f]
Syntaxprüfung
pattern ein regulärer Ausdruck, dem die gesamte Zeichenkette entsprechen muss
email E-Mail
identifier PHP-Bezeichner
url URL
uri URI
Umgebungsvalidierung
class ist vorhandene Klasse
interface ist existierende Schnittstelle
directory ist ein vorhandenes Verzeichnis
file ist existierende Datei

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