Validação de formulários

Controlos obrigatórios

Marcamos os controlos obrigatórios com o método setRequired(), cujo argumento é o texto da mensagem de erro, que será exibida se o utilizador não preencher o controlo. Se o argumento não for fornecido, a mensagem de erro padrão será usada.

$form->addText('name', 'Nome:')
	->setRequired('Por favor, insira o nome');

Regras

Adicionamos regras de validação aos controlos usando o método addRule(). O primeiro parâmetro é a regra, o segundo é o texto da mensagem de erro e o terceiro é o argumento da regra de validação.

$form->addPassword('password', 'Senha:')
	->addRule($form::MinLength, 'A senha deve ter pelo menos %d caracteres', 8);

As regras de validação são verificadas apenas se o utilizador preencher o controlo.

Nette vem com uma série de regras predefinidas, cujos nomes são constantes da classe Nette\Forms\Form. Podemos usar estas regras para todos os controlos:

Entradas de texto

Para os controlos addText(), addPassword(), addTextArea(), addEmail(), addInteger(), addFloat(), algumas das seguintes regras também podem ser usadas:

As regras de validação Integer, Numeric e Float convertem diretamente o valor para inteiro ou float, respetivamente. Além disso, a regra URL também aceita um endereço sem esquema (por exemplo, nette.org) e adiciona o esquema (https://nette.org). A expressão em Pattern e PatternIcase deve corresponder a todo o valor, ou seja, como se estivesse envolvida pelos caracteres ^ e $.

Número de itens

Para os controlos addMultiUpload(), addCheckboxList(), addMultiSelect(), as seguintes regras também podem ser usadas para limitar o número de itens selecionados ou ficheiros enviados:

Upload de ficheiros

Para os controlos addUpload(), addMultiUpload(), as seguintes regras também podem ser usadas:

MimeType e Image exigem a extensão PHP fileinfo. Elas detetam se um ficheiro ou imagem é do tipo desejado com base na sua assinatura e não verificam a integridade de todo o ficheiro. Se uma imagem não está danificada pode ser verificado, por exemplo, tentando carregá-la.

Mensagens de erro

Todas as regras predefinidas, exceto Pattern e PatternInsensitive, têm uma mensagem de erro padrão, então ela pode ser omitida. No entanto, fornecer e formular todas as mensagens sob medida tornará o formulário mais amigável ao utilizador.

Pode alterar as mensagens padrão na configuração, editando os textos no array Nette\Forms\Validator::$messages ou usando um tradutor.

No texto das mensagens de erro, podem ser usadas as seguintes strings de placeholder:

$form->addText('name', 'Nome:')
	->setRequired('Preencha por favor %label');

$form->addInteger('id', 'ID:')
	->addRule($form::Range, 'pelo menos %d e no máximo %d', [5, 10]);

$form->addInteger('id', 'ID:')
	->addRule($form::Range, 'no máximo %2$d e pelo menos %1$d', [5, 10]);

Condições

Além das regras, também é possível adicionar condições. Elas são escritas de forma semelhante às regras, mas em vez de addRule(), usamos o método addCondition() e, obviamente, não fornecemos nenhuma mensagem de erro (a condição apenas pergunta):

$form->addPassword('password', 'Senha:')
	// se a senha não tiver mais de 8 caracteres
	->addCondition($form::MaxLength, 8)
		// então deve conter um dígito
		->addRule($form::Pattern, 'Deve conter um dígito', '.*[0-9].*');

A condição também pode ser vinculada a outro controlo que não o atual, usando addConditionOn(). Como primeiro parâmetro, fornecemos uma referência ao controlo. Neste exemplo, o e-mail será obrigatório apenas se a caixa de seleção for marcada (o seu valor será true):

$form->addCheckbox('newsletters', 'enviar-me newsletters');

$form->addEmail('email', 'E-mail:')
	// se a caixa de seleção estiver marcada
	->addConditionOn($form['newsletters'], $form::Equal, true)
		// então exija o e-mail
		->setRequired('Insira o endereço de e-mail');

É possível criar estruturas complexas a partir de condições usando elseCondition() e endCondition():

$form->addText(/* ... */)
	->addCondition(/* ... */) // se a primeira condição for atendida
		->addConditionOn(/* ... */) // e a segunda condição em outro controlo
			->addRule(/* ... */) // exija esta regra
		->elseCondition() // se a segunda condição não for atendida
			->addRule(/* ... */) // exija estas regras
			->addRule(/* ... */)
		->endCondition() // voltamos à primeira condição
		->addRule(/* ... */);

Em Nette, é muito fácil reagir ao cumprimento ou não cumprimento de uma condição também no lado do JavaScript usando o método toggle(), veja JavaScript dinâmico.

Referência a outro controlo

Como argumento de uma regra ou condição, também é possível passar outro controlo do formulário. A regra então usará o valor inserido posteriormente pelo utilizador no navegador. Desta forma, é possível, por exemplo, validar dinamicamente que o controlo password contém a mesma string que o controlo password_confirm:

$form->addPassword('password', 'Senha');
$form->addPassword('password_confirm', 'Confirme a senha')
    ->addRule($form::Equal, 'As senhas inseridas não coincidem', $form['password']);

Regras e condições personalizadas

Ocasionalmente, chegamos a uma situação em que as regras de validação incorporadas em Nette não são suficientes e precisamos validar os dados do utilizador à nossa maneira. Em Nette, isso é muito simples!

Aos métodos addRule() ou addCondition(), é possível passar qualquer callback como primeiro parâmetro. Ele recebe o próprio controlo como primeiro parâmetro e retorna um valor booleano indicando se a validação foi bem-sucedida. Ao adicionar uma regra usando addRule(), é possível fornecer argumentos adicionais, que são então passados como segundo parâmetro.

Podemos criar o nosso próprio conjunto de validadores como uma classe com métodos estáticos:

class MyValidators
{
	// testa se o valor é divisível pelo argumento
	public static function validateDivisibility(BaseControl $input, $arg): bool
	{
		return $input->getValue() % $arg === 0;
	}

	public static function validateEmailDomain(BaseControl $input, $domain)
	{
		// outros validadores
	}
}

O uso é então muito simples:

$form->addInteger('num')
	->addRule(
		[MyValidators::class, 'validateDivisibility'],
		'O valor deve ser um múltiplo de %d',
		8,
	);

Regras de validação personalizadas também podem ser adicionadas ao JavaScript. A condição é que a regra seja um método estático. O seu nome para o validador JavaScript é formado pela junção do nome da classe sem barras invertidas \, um sublinhado _ e o nome do método. Por exemplo, App\MyValidators::validateDivisibility é escrito como AppMyValidators_validateDivisibility e adicionado ao objeto Nette.validators:

Nette.validators['AppMyValidators_validateDivisibility'] = (elem, args, val) => {
	return val % args === 0;
};

Evento onValidate

Após o envio do formulário, a validação é realizada, onde as regras individuais adicionadas via addRule() são verificadas e, em seguida, o evento onValidate é disparado. O seu handler pode ser usado para validação adicional, tipicamente para verificar a combinação correta de valores em múltiplos controlos do formulário.

Se um erro for detetado, passamos para o formulário usando o método addError(). Ele pode ser chamado num controlo específico ou diretamente no formulário.

protected function createComponentSignInForm(): Form
{
	$form = new Form;
	// ...
	$form->onValidate[] = [$this, 'validateSignInForm'];
	return $form;
}

public function validateSignInForm(Form $form, \stdClass $data): void
{
	if ($data->foo > 1 && $data->bar > 5) {
		$form->addError('Esta combinação não é possível.');
	}
}

Erros durante o processamento

Em muitos casos, descobrimos um erro apenas no momento em que estamos a processar um formulário válido, por exemplo, ao inserir um novo item no banco de dados e encontrar uma duplicidade de chaves. Nesse caso, passamos novamente o erro para o formulário usando o método addError(). Ele pode ser chamado num controlo específico ou diretamente no formulário:

try {
	$data = $form->getValues();
	$this->user->login($data->username, $data->password);
	$this->redirect('Home:');

} catch (Nette\Security\AuthenticationException $e) {
	if ($e->getCode() === Nette\Security\Authenticator::InvalidCredential) {
		$form->addError('Senha inválida.');
	}
}

Se possível, recomendamos anexar o erro diretamente ao controlo do formulário, pois ele será exibido ao lado dele ao usar o renderizador padrão.

$form['date']->addError('Desculpe, mas esta data já está ocupada.');

Pode chamar addError() repetidamente para passar várias mensagens de erro ao formulário ou controlo. Pode obtê-las usando getErrors().

Atenção, $form->getErrors() retorna um resumo de todas as mensagens de erro, incluindo aquelas que foram passadas diretamente para controlos individuais, não apenas diretamente para o formulário. Mensagens de erro passadas apenas para o formulário podem ser obtidas via $form->getOwnErrors().

Modificação da entrada

Usando o método addFilter(), podemos modificar o valor inserido pelo utilizador. Neste exemplo, toleraremos e removeremos espaços no código postal:

$form->addText('zip', 'Código Postal:')
	->addFilter(function ($value) {
		return str_replace(' ', '', $value); // removemos espaços do código postal
	})
	->addRule($form::Pattern, 'Código Postal não está no formato de cinco dígitos', '\d{5}');

O filtro é integrado entre as regras de validação e condições, portanto, a ordem dos métodos importa, ou seja, o filtro e a regra são chamados na mesma ordem que os métodos addFilter() e addRule().

Validação JavaScript

A linguagem para formular condições e regras é muito poderosa. Todas as construções funcionam tanto no lado do servidor quanto no lado do JavaScript. Elas são transferidas em atributos HTML data-nette-rules como JSON. A validação em si é então realizada por um script que captura o evento submit do formulário, percorre os controlos individuais e executa a validação apropriada.

Esse script é netteForms.js e está disponível em várias fontes possíveis:

Pode inserir o script diretamente na página HTML a partir de um CDN:

<script src="https://unpkg.com/nette-forms@3"></script>

Ou copiá-lo localmente para a pasta pública do projeto (por exemplo, de vendor/nette/forms/src/assets/netteForms.min.js):

<script src="/path/to/netteForms.min.js"></script>

Ou instalar via npm:

npm install nette-forms

E, em seguida, carregar e executar:

import netteForms from 'nette-forms';
netteForms.initOnLoad();

Alternativamente, pode carregá-lo diretamente da pasta vendor:

import netteForms from '../path/to/vendor/nette/forms/src/assets/netteForms.js';
netteForms.initOnLoad();

JavaScript dinâmico

Quer exibir os campos para inserir o endereço apenas se o utilizador escolher enviar o produto pelo correio? Sem problemas. A chave é o par de métodos addCondition() & toggle():

$form->addCheckbox('send_it')
	->addCondition($form::Equal, true)
		->toggle('#address-container');

Este código diz que quando a condição é atendida, ou seja, quando a caixa de seleção está marcada, o elemento HTML #address-container será visível. E vice-versa. Assim, colocamos os controlos do formulário com o endereço do destinatário num contêiner com este ID e, ao clicar na caixa de seleção, eles serão ocultados ou exibidos. Isso é garantido pelo script netteForms.js.

Como argumento do método toggle(), é possível passar qualquer seletor. Por razões históricas, uma string alfanumérica sem outros caracteres especiais é entendida como o ID do elemento, ou seja, da mesma forma que se fosse precedida pelo caractere #. O segundo parâmetro opcional permite inverter o comportamento, ou seja, se usássemos toggle('#address-container', false), o elemento seria exibido apenas se a caixa de seleção não estivesse marcada.

A implementação padrão em JavaScript altera a propriedade hidden dos elementos. No entanto, podemos facilmente alterar o comportamento, por exemplo, adicionando uma animação. Basta sobrescrever o método Nette.toggle em JavaScript com a sua própria solução:

Nette.toggle = (selector, visible, srcElement, event) => {
	document.querySelectorAll(selector).forEach((el) => {
		// ocultamos ou exibimos 'el' de acordo com o valor 'visible'
	});
};

Desativação da validação

Às vezes, pode ser útil desativar a validação. Se o pressionamento de um botão de envio não deve realizar a validação (adequado para botões Cancelar ou Visualizar), desativamo-la com o método $submit->setValidationScope([]). Se deve realizar apenas validação parcial, podemos especificar quais campos ou contêineres de formulário devem ser validados.

$form->addText('name')
	->setRequired();

$details = $form->addContainer('details');
$details->addInteger('age')
	->setRequired('age');
$details->addInteger('age2')
	->setRequired('age2');

$form->addSubmit('send1'); // Valida o formulário inteiro
$form->addSubmit('send2')
	->setValidationScope([]); // Não valida nada
$form->addSubmit('send3')
	->setValidationScope([$form['name']]); // Valida apenas o controlo name
$form->addSubmit('send4')
	->setValidationScope([$form['details']['age']]); // Valida apenas o controlo age
$form->addSubmit('send5')
	->setValidationScope([$form['details']]); // Valida o contêiner details

setValidationScope não afeta o evento onValidate no formulário, que será chamado sempre. O evento onValidate num contêiner será disparado apenas se este contêiner estiver marcado para validação parcial.