Validadores de valores

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

Instalação:

composer require nette/utils

Todos os exemplos assumem que um alias foi criado:

use Nette\Utils\Validators;

Uso Básico

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

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:

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:

Asserções

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

Verifica se o valor é um dos tipos esperados separados por uma barra vertical. Se não for, lança uma exceção Nette\Utils\AssertionException. A palavra variable no texto da exceção pode ser substituída por outra usando o parâmetro $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 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 Nette\Utils\AssertionException. A string item '%' in array no texto da exceção pode ser substituída por outra usando o 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

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

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

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, que também podem estar em unicode.

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

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

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.

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

Verifica se o valor é 0, '', false ou null.

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

isNumeric (mixed $value): bool

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

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

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

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

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

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

isBuiltinType (string $type): bool

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

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

isTypeDeclaration (string $type): bool

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

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

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

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

isUnicode (mixed $value): bool

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

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

isUrl (mixed $value): bool

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

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

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