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

.[perex]
¿Necesitas verificar rápida y fácilmente que una variable contiene, por ejemplo, una dirección de correo electrónico válida? Entonces le resultará útil [api:Nette\Utils\Validators], una clase estática con funciones útiles para validar valores.


Instalación:

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

Todos los ejemplos asumen que el siguiente alias de clase está definido:

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


Uso básico .[#toc-basic-usage]
==============================

La clase `Validators` tiene un número de métodos para validar valores, como [isList() |#isList()], [isUnicode() |#isUnicode()], [isEmail() |#isEmail()], [isUrl() |#isUrl()], etc. para usar en tu código:

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

Además, puede verificar si el valor satisface los llamados tipos [esperados |#expected types], que es una cadena donde las opciones individuales están separadas por una barra vertical `|`. Esto facilita la verificación de tipos de unión utilizando [if() |#if()]:

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

Pero también te da la oportunidad de crear un sistema donde es necesario escribir las expectativas como cadenas (por ejemplo en anotaciones o configuración) y luego verificar de acuerdo a ellas.

También puede declarar [aserción |#assert], que lanza una excepción si no se cumple.


Tipos esperados .[#toc-expected-types]
======================================

Un tipo esperado es una cadena formada por una o más variantes separadas por una barra vertical `|`, similar to writing types in PHP (ie. `'int|string|bool')`. También se permite la notación nulable `?int`.

Una matriz en la que todos los elementos son de un tipo determinado se escribe de la forma `int[]`.

Algunos tipos pueden ir seguidos de dos puntos y la longitud `:length` o el rango `:[min]..[max]` por ejemplo, `string:10` (cadena con una longitud de 10 bytes), `float:10..` (número 10 y mayores), `array:..10` (matriz de hasta diez elementos) o `list:10..20` (lista de 10 a 20 elementos), o una expresión regular para `pattern:[0-9]+`.

Resumen de tipos y reglas:

.[wide]
| Tipos PHP ||
|--------------------------
| `array` .{width: 140px} | range for the number of items can be given
| `bool` |
| `float` | rango para el valor puede ser dado
| `int` | rango para el valor puede ser dado
| `null` |
| `object` |
| `resource` |
| `scalar` | int\|float\|bool\|string
| `string` | se puede indicar la longitud en bytes
| `callable` |
| `iterable` |
| `mixed` |
|------------------------------------------------
| Pseudotipos ||
|------------------------------------------------
| `list` | [array indexado |#isList], se puede dar un rango para el número de elementos
| `none` | valor vacío: `''`, `null`, `false`
| `number` | int\|float
| `numeric` | [número con representación textual |#isNumeric]
| `numericint`| [número entero con representación textual |#isNumericInt]
| `unicode` | [Cadena UTF-8 |#isUnicode], se puede dar un rango para la longitud en caracteres
|------------------------------------------------
| Clase de caracteres (no puede ser una cadena vacía) ||
|------------------------------------------------
| `alnum` | todos los caracteres son alfanuméricos
| `alpha` | todos los caracteres son letras `[A-Za-z]`
| `digit` | todos los caracteres son dígitos
| `lower` | todos los caracteres son minúsculas. `[a-z]`
| `space` | todos los caracteres son espacios.
| `upper` | todos los caracteres son mayúsculas. `[A-Z]`
| `xdigit` | todos los caracteres son dígitos hexadecimales. `[0-9A-Fa-f]`
|------------------------------------------------
| Validación de sintaxis ||
|------------------------------------------------
| `pattern` | una expresión regular con la que debe coincidir **toda** la cadena
| `email` | [Correo electrónico |#isEmail]
| `identifier` | [Identificador PHP |#isPhpIdentifier]
| `url` | [URL |#isUrl]
| `uri` | [URI |#isUri]
|------------------------------------------------
| Validación del entorno ||
|------------------------------------------------
| `class` | es una clase existente
| `interface` | es una interfaz existente
| `directory` | es un directorio existente
| `file` | es un archivo existente


Afirmación .[#toc-assertion]
============================


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

Verifica que el valor es de los [tipos esperados |#expected types] separados por una tubería. Si no es así, lanza la excepción [api:Nette\Utils\AssertionException]. La palabra `variable` del mensaje de excepción puede sustituirse por el parámetro `$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 que el elemento `$key` en el array `$array` es de los [tipos esperados |#expected types] separados por una tubería. Si no es así, lanza la excepción [api:Nette\Utils\AssertionException]. La cadena `item '%' in array` del mensaje de excepción puede sustituirse por el parámetro `$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.
```


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


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

Comprueba si el valor es de los [tipos esperados |#expected types] separados por una tubería.

```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 que el valor es una dirección de correo electrónico válida. No verifica que el dominio exista realmente, sólo se verifica la sintaxis. La función también cuenta con futuros [TLD |https://en.wikipedia.org/wiki/Top-level_domain], que también pueden estar en unicode.

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


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

Comprueba si el valor está dentro del rango dado `[min, max]`donde se puede omitir el límite superior o inferior (`null`). Se pueden comparar números, cadenas y objetos DateTime.

Si faltan ambos límites (`[null, null]`) o el valor es `null`, devuelve `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]
------------------------------------

Comprueba si el valor es `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]
---------------------------------------

Comprueba si el valor es un número o un número escrito en una cadena.

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

Comprueba si el valor es un número entero o un número entero escrito en una cadena.

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

Comprueba si el valor es un identificador sintácticamente válido en PHP, por ejemplo para nombres de clases, métodos, funciones, etc.

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


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

Determina si `$type` es un tipo incorporado en PHP. De lo contrario, es el nombre de la clase.

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


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

Comprueba si la declaración de tipo es sintácticamente correcta.

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

Determine si `$type` es uno de los tipos internos `self`, `parent`, `static`.

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


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

Comprueba si el valor es una cadena UTF-8 válida.

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


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

Comprueba si el valor es una dirección URL válida.

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

Comprueba que el valor es una dirección URI válida, es decir, realmente una cadena que comienza con un esquema sintácticamente válido.

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