Nette Documentation Preview

syntax
Validatori di valore
********************

.[perex]
Avete bisogno di verificare rapidamente e facilmente che una variabile contenga, ad esempio, un indirizzo e-mail valido? Allora vi sarà utile [api:Nette\Utils\Validators], una classe statica con utili funzioni per la validazione dei valori.


Installazione:

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

Tutti gli esempi presuppongono che sia definito il seguente alias di classe:

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


Uso di base .[#toc-basic-usage]
===============================

La classe `Validators` ha una serie di metodi per la validazione dei valori, come [isList() |#isList()], [isUnicode() |#isUnicode()], [isEmail() |#isEmail()], [isUrl() |#isUrl()], ecc. da utilizzare nel codice:

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

Inoltre, è in grado di verificare se il valore soddisfa i cosiddetti [tipi attesi |#expected types], ovvero una stringa in cui le singole opzioni sono separate da una barra verticale `|`. In questo modo è facile verificare i tipi di unione usando [if() |#if()]:

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

Ma offre anche l'opportunità di creare un sistema in cui è necessario scrivere le aspettative come stringhe (ad esempio nelle annotazioni o nella configurazione) e poi verificarle in base ad esse.

Si possono anche dichiarare [asserzioni |#assert], che lanciano un'eccezione se non sono soddisfatte.


Tipi attesi .[#toc-expected-types]
==================================

Un tipo atteso è una stringa composta da una o più varianti separate da una barra verticale `|`, similar to writing types in PHP (ie. `'int|string|bool')`. Sono ammesse anche notazioni nulle `?int`.

Un array in cui tutti gli elementi sono di un certo tipo è scritto nella forma `int[]`.

Alcuni tipi possono essere seguiti da due punti e dalla lunghezza `:length` o dall'intervallo `:[min]..[max]`ad esempio `string:10` (una stringa di lunghezza pari a 10 byte), `float:10..` (numero 10 o più grande), `array:..10` (array fino a dieci elementi) o `list:10..20` (elenco da 10 a 20 elementi), oppure un'espressione regolare per `pattern:[0-9]+`.

Panoramica dei tipi e delle regole:

.[wide]
| Tipi di PHP ||
|--------------------------
| `array` .{width: 140px} | è possibile indicare un intervallo per il numero di elementi
| `bool` |
| `float` | può essere dato un intervallo per il valore
| `int` | può essere dato un intervallo per il valore
| `null` |
| `object` |
| `resource` |
| `scalar` | int\float\bool\stringhe
| `string` | è possibile indicare un intervallo per la lunghezza in byte
| `callable` |
| `iterable` |
| `mixed` |
|------------------------------------------------
| pseudo-tipi ||
|------------------------------------------------
| `list` | [array indicizzato |#isList], può essere dato un intervallo per il numero di elementi
| `none` | valore vuoto: `''`, `null`, `false`
| `number` | int\\float
| `numeric` | [numero con rappresentazione testuale |#isNumeric]
| `numericint`| [numero intero comprensivo di rappresentazione testuale |#isNumericInt]
| `unicode` | [stringa UTF-8 |#isUnicode], è possibile indicare un intervallo per la lunghezza in caratteri
|------------------------------------------------
| classe di caratteri (non può essere una stringa vuota) ||
|------------------------------------------------
| `alnum` | tutti i caratteri sono alfanumerici
| `alpha` | tutti i caratteri sono lettere `[A-Za-z]`
| `digit` | tutti i caratteri sono cifre
| `lower` | tutti i caratteri sono lettere minuscole `[a-z]`
| `space` | tutti i caratteri sono spazi
| `upper` | tutti i caratteri sono lettere maiuscole `[A-Z]`
| `xdigit` | tutti i caratteri sono cifre esadecimali `[0-9A-Fa-f]`
|------------------------------------------------
| convalida della sintassi ||
|------------------------------------------------
| `pattern` | un'espressione regolare a cui l'intera stringa deve corrispondere
| `email` | [Email |#isEmail]
| `identifier`| [Identificatore PHP |#isPhpIdentifier]
| `url` | [URL |#isUrl]
| `uri` | [URI |#isUri]
|------------------------------------------------
| Convalida dell'ambiente
|------------------------------------------------
| `class` | è una classe esistente
| `interface` | è un'interfaccia esistente
| `directory` | è una directory esistente
| `file` | è un file esistente


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


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

Verifica che il valore sia dei [tipi previsti |#expected types], separati da pipe. In caso contrario, lancia l'eccezione [api:Nette\Utils\AssertionException]. La parola `variable` nel messaggio di eccezione può essere sostituita dal parametro `$label`.

```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]
-----------------------------------------------------------------------------------------------------

Verifica che l'elemento `$key` nell'array `$array` sia dei [tipi previsti |#expected types] separati da pipe. In caso contrario, lancia l'eccezione [api:Nette\Utils\AssertionException]. La stringa `item '%' in array` nel messaggio di eccezione può essere sostituita dal parametro `$label`.

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


Validatori .[#toc-validators]
=============================


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

Controlla se il valore è dei [tipi previsti |#expected types], separati da pipe.

```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]
-------------------------------------

Verifica che il valore sia un indirizzo e-mail valido. Non verifica l'effettiva esistenza del dominio, ma solo la sintassi. La funzione tiene conto anche dei [TLD |https://en.wikipedia.org/wiki/Top-level_domain] futuri, che potrebbero essere anche in unicode.

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


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

Verifica se il valore è compreso nell'intervallo indicato `[min, max]`dove il limite superiore o inferiore può essere omesso (`null`). È possibile confrontare numeri, stringhe e oggetti DateTime.

Se mancano entrambi i limiti (`[null, null]`) o il valore è `null`, restituisce `false`.

```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]
------------------------------------

Controlla se il valore è `0`, `''`, `false` o `null`.

```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]
---------------------------------------

Controlla se il valore è un numero o un numero scritto in una stringa.

```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]
------------------------------------------

Controlla se il valore è un numero intero o un numero intero scritto in una stringa.

```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]
----------------------------------------------

Controlla se il valore è un identificatore sintatticamente valido in PHP, ad esempio per i nomi di classi, metodi, funzioni, ecc.

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


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

Determina se `$type` è un tipo incorporato in PHP. Altrimenti, è il nome della classe.

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


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

Controlla se la dichiarazione del tipo è sintatticamente corretta.

```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]
--------------------------------------------

Determina se `$type` è uno dei tipi interni `self`, `parent`, `static`.

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


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

Verifica se il valore è una stringa UTF-8 valida.

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


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

Controlla se il valore è un indirizzo URL valido.

```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]
------------------------------------

Verifica che il valore sia un indirizzo URI valido, cioè una stringa che inizia con uno schema sintatticamente valido.

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

Validatori di valore

Avete bisogno di verificare rapidamente e facilmente che una variabile contenga, ad esempio, un indirizzo e-mail valido? Allora vi sarà utile Nette\Utils\Validators, una classe statica con utili funzioni per la validazione dei valori.

Installazione:

composer require nette/utils

Tutti gli esempi presuppongono che sia definito il seguente alias di classe:

use Nette\Utils\Validators;

Uso di base

La classe Validators ha una serie di metodi per la validazione dei valori, come isList(), isUnicode(), isEmail(), isUrl(), ecc. da utilizzare nel codice:

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

Inoltre, è in grado di verificare se il valore soddisfa i cosiddetti tipi attesi, ovvero una stringa in cui le singole opzioni sono separate da una barra verticale |. In questo modo è facile verificare i tipi di unione usando if():

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

Ma offre anche l'opportunità di creare un sistema in cui è necessario scrivere le aspettative come stringhe (ad esempio nelle annotazioni o nella configurazione) e poi verificarle in base ad esse.

Si possono anche dichiarare asserzioni, che lanciano un'eccezione se non sono soddisfatte.

Tipi attesi

Un tipo atteso è una stringa composta da una o più varianti separate da una barra verticale |, similar to writing types in PHP (ie. 'int|string|bool'). Sono ammesse anche notazioni nulle ?int.

Un array in cui tutti gli elementi sono di un certo tipo è scritto nella forma int[].

Alcuni tipi possono essere seguiti da due punti e dalla lunghezza :length o dall'intervallo :[min]..[max]ad esempio string:10 (una stringa di lunghezza pari a 10 byte), float:10.. (numero 10 o più grande), array:..10 (array fino a dieci elementi) o list:10..20 (elenco da 10 a 20 elementi), oppure un'espressione regolare per pattern:[0-9]+.

Panoramica dei tipi e delle regole:

Tipi di PHP
array è possibile indicare un intervallo per il numero di elementi
bool  
float può essere dato un intervallo per il valore
int può essere dato un intervallo per il valore
null  
object  
resource  
scalar int\float\bool\stringhe
string è possibile indicare un intervallo per la lunghezza in byte
callable  
iterable  
mixed  
pseudo-tipi
list array indicizzato, può essere dato un intervallo per il numero di elementi
none valore vuoto: '', null, false
number int\\float
numeric numero con rappresentazione testuale
numericint numero intero comprensivo di rappresentazione testuale
unicode stringa UTF-8, è possibile indicare un intervallo per la lunghezza in caratteri
classe di caratteri (non può essere una stringa vuota)
alnum tutti i caratteri sono alfanumerici
alpha tutti i caratteri sono lettere [A-Za-z]
digit tutti i caratteri sono cifre
lower tutti i caratteri sono lettere minuscole [a-z]
space tutti i caratteri sono spazi
upper tutti i caratteri sono lettere maiuscole [A-Z]
xdigit tutti i caratteri sono cifre esadecimali [0-9A-Fa-f]
convalida della sintassi
pattern un'espressione regolare a cui l'intera stringa deve corrispondere
email Email
identifier Identificatore PHP
url URL
uri URI
Convalida dell'ambiente  
class è una classe esistente
interface è un'interfaccia esistente
directory è una directory esistente
file è un file esistente

Asserzione

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

Verifica che il valore sia dei tipi previsti, separati da pipe. In caso contrario, lancia l'eccezione Nette\Utils\AssertionException. La parola variable nel messaggio di eccezione può essere sostituita dal parametro $label.

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

Verifica che l'elemento $key nell'array $array sia dei tipi previsti separati da pipe. In caso contrario, lancia l'eccezione Nette\Utils\AssertionException. La stringa item '%' in array nel messaggio di eccezione può essere sostituita dal parametro $label.

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

Validatori

is($value, string $expected)bool

Controlla se il valore è dei tipi previsti, separati da pipe.

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

Verifica che il valore sia un indirizzo e-mail valido. Non verifica l'effettiva esistenza del dominio, ma solo la sintassi. La funzione tiene conto anche dei TLD futuri, che potrebbero essere anche in unicode.

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

isInRange(mixed $value, array $range)bool

Verifica se il valore è compreso nell'intervallo indicato [min, max]dove il limite superiore o inferiore può essere omesso (null). È possibile confrontare numeri, stringhe e oggetti DateTime.

Se mancano entrambi i limiti ([null, null]) o il valore è null, restituisce false.

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

Controlla se il valore è 0, '', false o null.

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

isNumeric(mixed $value): bool

Controlla se il valore è un numero o un numero scritto in una stringa.

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

Controlla se il valore è un numero intero o un numero intero scritto in una stringa.

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

Controlla se il valore è un identificatore sintatticamente valido in PHP, ad esempio per i nomi di classi, metodi, funzioni, ecc.

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

isBuiltinType(string $type)bool

Determina se $type è un tipo incorporato in PHP. Altrimenti, è il nome della classe.

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

isTypeDeclaration(string $type)bool

Controlla se la dichiarazione del tipo è sintatticamente corretta.

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

Determina se $type è uno dei tipi interni self, parent, static.

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

isUnicode(mixed $value): bool

Verifica se il valore è una stringa UTF-8 valida.

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

isUrl(mixed $value): bool

Controlla se il valore è un indirizzo URL valido.

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

Verifica che il valore sia un indirizzo URI valido, cioè una stringa che inizia con uno schema sintatticamente valido.

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