Validadores de valores

¿Necesita comprobar rápida y fácilmente que una variable contiene, por ejemplo, una dirección de correo válida? Entonces le vendrá bien Nette\Utils\Validators, una clase estática con funciones útiles para validar valores.

Instalación:

composer require nette/utils

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

use Nette\Utils\Validators;

Uso básico

La clase Validators ofrece numerosos métodos para comprobar valores, como isUnicode(), isEmail(), isUrl(), etc., para usarlos en su código:

if (!Validators::isEmail($email)) {
	throw new InvalidArgumentException('Invalid email address provided.');
}

Puede además comprobar si el valor cumple los llamados Tipos esperados, que son una cadena donde las distintas opciones se separan con una barra vertical |. Así resulta fácil verificar tipos union con is():

if (!Validators::is($val, 'int|string|bool')) {
	// Trata el tipo no válido...
}

Esto le permite también crear sistemas donde las expectativas deben escribirse como cadenas (por ejemplo, en anotaciones o configuraciones) y validar después los valores contra ellas.

También puede declarar una aserción, que lanza una excepción si la expectativa no se cumple.

Tipos esperados

Los tipos esperados forman una cadena compuesta por una o varias variantes separadas por una barra |, de forma parecida a como se escriben los tipos en PHP (por ejemplo, 'int|string|bool'). También se admite la notación nullable ?int.

Un array cuyos elementos son todos de cierto tipo se escribe en la forma int[].

Algunos tipos pueden ir seguidos de dos puntos y una longitud :length o un rango :[min]..[max], por ejemplo string:10 (una cadena de 10 bytes de longitud), float:10.. (un número igual o mayor que 10), array:..10 (un array de hasta diez elementos) o list:10..20 (una lista de 10 a 20 elementos), o bien una expresión regular como pattern:[0-9]+.

Resumen de los tipos y las reglas:

Aserción

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

Comprueba que el valor sea uno de los Tipos esperados separados por una barra. Si no lo es, lanza Nette\Utils\AssertionException. La palabra variable del mensaje de la excepción se puede sustituir mediante el parámetro $label.

Validators::assert('Nette', 'string:5'); // OK (la cadena 'Nette' tiene 5 bytes)
Validators::assert('Lorem ipsum dolor sit', 'string:78');
// AssertionException: The variable expects to be string in range 78, string 'Lorem ipsum dolor sit' given.

assertField (array $array, string|int $key, ?string $expected=null, string $label="item '%' in array"): void

Comprueba que el elemento de clave $key del array $array sea uno de los Tipos esperados separados por una barra. Si no lo es, lanza Nette\Utils\AssertionException. La cadena item '%' in array del mensaje de la excepción se puede sustituir mediante el parámetro $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.

Validadores

is ($value, string $expected): bool

Comprueba si el valor es uno de los Tipos esperados separados por una barra.

Validators::is(1, 'int|float');  // true
Validators::is(23, 'int:0..10'); // false (23 está fuera del rango 0-10)
Validators::is('Nette Framework', 'string:15');     // true, la longitud es de 15 bytes
Validators::is('Nette Framework', 'string:8..');    // true
Validators::is('Nette Framework', 'string:30..40'); // false

everyIs (iterable $values, string $expected): bool

Comprueba si todos los valores del iterable son uno de los Tipos esperados separados por una barra. Funciona como is() aplicado a cada elemento.

$list = ['Nette', 'Framework', 2020];
Validators::everyIs($list, 'string');     // false (2020 no es una cadena)
Validators::everyIs($list, 'string|int'); // true

isEmail (string $value): bool

Comprueba que el valor sea una dirección de correo electrónico válida. No verifica que el dominio exista realmente, solo la sintaxis. La función tiene además en cuenta los futuros TLD, que también pueden estar en unicode.

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

isInRange (mixed $value, array $range): bool

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

Si faltan ambos límites ([null, null]) o el valor es null, devuelve false.

Validators::isInRange(5, [0, 5]);     // true
Validators::isInRange(23, [null, 5]); // false
Validators::isInRange(23, [5]);       // true (equivale a [5, null])
Validators::isInRange(1, [5]);        // false

isNone (mixed $value): bool

Comprueba si el valor es 0, '', false, null, 0.0 o [].

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

isNumeric (mixed $value): bool

Comprueba si el valor es un número o un número representado como cadena.

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 (no se acepta la notación científica)

isNumericInt (mixed $value): bool

Comprueba si el valor es un entero o un entero representado como cadena.

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

Comprueba si el valor es un identificador sintácticamente válido en PHP (por ejemplo, para nombres de clase, de método, de función, etc.).

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

isBuiltinType (string $type): bool

Determina si $type es un tipo nativo de PHP (por ejemplo, string, int, array, bool). En caso contrario, se considera un nombre de clase.

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

isTypeDeclaration (string $type): bool

Comprueba si la cadena de declaración de tipo dada es sintácticamente válida según las reglas de declaración de tipos de PHP (incluidos los tipos union, intersection y DNF).

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 $name): bool

Determina si $name es una de las palabras clave internas de tipo self, parent o static.

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

isUnicode (mixed $value): bool

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

Validators::isUnicode('nette'); // true
Validators::isUnicode('');      // true
Validators::isUnicode("\xA0");  // false (secuencia UTF-8 no válida)

isUrl (string $value): bool

Comprueba si el valor es una dirección URL absoluta válida según la RFC 3986.

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 (esta función no valida la parte userinfo)
Validators::isUrl('nette.org');                   // false (falta el esquema)

isUri (string $value): bool

Comprueba que el valor sea una dirección URI válida, es decir, una cadena que empieza por un esquema sintácticamente válido seguido de dos puntos (por ejemplo, http:, https:, mailto:, ftp:).

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