Validadores de valores
**********************

.[perex]
Precisa verificar rápida e facilmente se uma variável contém, por exemplo, um endereço de e-mail válido? Então [api:Nette\Utils\Validators], uma classe estática com funções úteis para validação de valores, será útil para você.


Instalação:

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

Todos os exemplos assumem que um alias foi criado:

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


Uso Básico
==========

A classe possui vários métodos para verificar valores, como [#isUnicode], [#isEmail], [#isUrl], etc., para uso em seu código:

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

Além disso, pode verificar se um valor é um dos chamados [#tipos esperados], que é uma string onde as opções individuais são separadas por uma barra vertical `|`. Podemos facilmente verificar vários tipos usando [#is()]:

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

Mas isso também nos dá a possibilidade de criar um sistema onde as expectativas precisam ser escritas como strings (por exemplo, em anotações ou configuração) e depois verificar os valores de acordo com elas.

Para tipos esperados, também podemos usar a asserção [#assert()], que lança uma exceção se não for satisfeita.


Tipos Esperados
===============

Os tipos esperados formam uma string que consiste em uma ou mais variantes separadas por uma barra vertical `|`, semelhante à forma como os tipos são escritos em PHP (por exemplo, `'int|string|bool'`). A notação anulável `?int` também é aceita.

Arrays onde todos os elementos são de um certo tipo são escritos na forma `int[]`.

Alguns tipos podem ser seguidos por dois pontos e um comprimento `:length` ou um intervalo `:[min]..[max]`, por exemplo, `string:10` (string com 10 bytes de comprimento), `float:10..` (número 10 ou maior), `array:..10` (array com até dez elementos) ou `list:10..20` (lista com 10 a 20 elementos), ou uma expressão regular para `pattern:[0-9]+`.

Visão geral de tipos e regras:

.[wide]
| Tipos PHP   ||
|--------------------------
| `array` .{width: 140px} | pode especificar um intervalo para o número de elementos
| `bool`     |
| `float`    | pode especificar um intervalo para o valor
| `int`      | pode especificar um intervalo para o valor
| `null`     |
| `object`   |
| `resource` |
| `scalar`   | int\|float\|bool\|string
| `string`   | pode especificar um intervalo para o comprimento em bytes
| `callable` |
| `iterable` |
| `mixed`    |
|--------------------------
| pseudo-tipos ||
|------------------------------------------------
| `list`      | array indexado, pode especificar um intervalo para o número de elementos
| `none`      | valor vazio: `''`, `null`, `false`
| `number`    | int\|float
| `numeric`   | [número incluindo representação textual |#isNumeric]
| `numericint`| [número inteiro incluindo representação textual |#isNumericInt]
| `unicode`   | [string UTF-8 |#isUnicode], pode especificar um intervalo para o comprimento em caracteres
|--------------------------
| classe de caracteres (não pode ser uma string vazia) ||
|------------------------------------------------
| `alnum`   | todos os caracteres são alfanuméricos
| `alpha`   | todos os caracteres são letras `[A-Za-z]`
| `digit`   | todos os caracteres são dígitos
| `lower`   | todos os caracteres são letras minúsculas `[a-z]`
| `space`   | todos os caracteres são espaços
| `upper`   | todos os caracteres são letras maiúsculas `[A-Z]`
| `xdigit`  | todos os caracteres são dígitos hexadecimais `[0-9A-Fa-f]`
|--------------------------
| validação de sintaxe ||
|------------------------------------------------
| `pattern`   | expressão regular que deve corresponder à string **inteira**
| `email`     | [E-mail |#isEmail]
| `identifier`| [Identificador PHP |#isPhpIdentifier]
| `url`       | [URL |#isUrl]
| `uri`       | [URI |#isUri]
|--------------------------
| verificação de ambiente ||
|------------------------------------------------
| `class`     | é uma classe existente
| `interface` | é uma interface existente
| `directory` | é um diretório existente
| `file`      | é um arquivo existente


Asserções
=========


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

Verifica se o valor é um dos [#tipos esperados] separados por uma barra vertical. Se não for, lança uma exceção [api:Nette\Utils\AssertionException]. A palavra `variable` no texto da exceção pode ser substituída por outra usando o parâmetro `$label`.

```php
Validators::assert('Nette', 'string:5'); // OK
Validators::assert('Lorem ipsum dolor sit', 'string:78');
// AssertionException: A variável espera ser string:78, string 'Lorem ipsum dolor sit' fornecida.
```


assertField(array $array, string|int $key, ?string $expected=null, ?string $label=null): void .[method]
-------------------------------------------------------------------------------------------------------

Verifica se o elemento sob a chave `$key` no array `$array` é um dos [#tipos esperados] separados por uma barra vertical. Se não for, lança uma exceção [api:Nette\Utils\AssertionException]. A string `item '%' in array` no texto da exceção pode ser substituída por outra usando o parâmetro `$label`.

```php
$arr = ['foo' => 'Nette'];

Validators::assertField($arr, 'foo', 'string:5'); // OK
Validators::assertField($arr, 'bar', 'string:15');
// AssertionException: Item 'bar' ausente no array.
Validators::assertField($arr, 'foo', 'int');
// AssertionException: O item 'foo' no array espera ser int, string 'Nette' fornecida.
```


Validadores
===========


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

Verifica se o valor é um dos [#tipos esperados] separados por uma barra vertical.

```php
Validators::is(1, 'int|float');  // true
Validators::is(23, 'int:0..10'); // false
Validators::is('Nette Framework', 'string:15');     // true, o comprimento é de 15 bytes
Validators::is('Nette Framework', 'string:8..');    // true
Validators::is('Nette Framework', 'string:30..40'); // false
```


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

Verifica se o valor é um endereço de e-mail válido. Não verifica se o domínio realmente existe, apenas a sintaxe é verificada. A função também considera futuros [TLDs|https://pt.wikipedia.org/wiki/Dom%C3%ADnio_de_n%C3%ADvel_superior], que também podem estar em 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 o valor está dentro do intervalo fornecido `[min, max]`, onde o limite superior ou inferior pode ser omitido (`null`). Números, strings e objetos DateTime podem ser comparados.

Se ambos os limites estiverem faltando (`[null, null]`) ou o valor for `null`, retorna `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]
------------------------------------

Verifica se o valor é `0`, `''`, `false` ou `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]
---------------------------------------

Verifica se o valor é um número ou um número escrito em uma string.

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

Verifica se o valor é um número inteiro ou um número inteiro escrito em uma string.

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

Verifica se o valor é um identificador sintaticamente válido em PHP, por exemplo, para nomes de classes, métodos, funções, etc.

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


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

Verifica se `$type` é um tipo embutido do PHP. Caso contrário, é um nome de classe.

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


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

Verifica se a declaração de tipo fornecida é sintaticamente válida.

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

Verifica se `$type` é um dos tipos internos `self`, `parent`, `static`.

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


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

Verifica se o valor é uma string UTF-8 válida.

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


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

Verifica se o valor é um endereço URL válido.

```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 se o valor é um endereço URI válido, ou seja, uma string que começa com um esquema sintaticamente válido.

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