Code Igniter Versão 1.5.2 - Guia do Usuário

Validação de Formulário

Antes de explicar a abordagem do Code Igniter's com a validação de dados, vamos descrever o cenário ideal:

  1. Um formulário é exibido.
  2. Você preenche e o submete.
  3. Se você submeteu alguma informação inválida ou esqueceu algum item obrigatórioa, o formulário é re-exibido contendo seus dados e uma mensagem de erro descrivendo o problema.
  4. Este processo continuará até você submeter um formulário totalmente válido.

No lado de recebimento dos dados, o script deve:

  1. Conferir os dados que são obrigatórios.
  2. Verifique que os dados são do tipo correto e correspondem, respectivamente, com os critérios corretos. (Por exemplo, se um nome de usuário é submetido, ele deve ser validado de modo a conter apenas caracteres permitidos. Deve ter um número mínimo de caracteres e não exceder o número máximo. O nome de usuário não pode ser um já existente ou nem mesmo uma palavra reservada. Etc.)
  3. Limpar os dados para segurança (exemplo: limpar SQL injections).
  4. Pré-formatar os dados caso precise (É necessário retirar algum espaço em branco? Codificar/Encodar HTML ? Etc.)
  5. Preparar os dados para inserção na base de dados.

Embora não haja nada de complexo no processo acima, ele frequentemetne requer um considerável números de linhas de código e para exibição de mensagens de erro, várias estruturas de controle são normalmente colocadas dentro do formulário HTML. Valdação de Formulário, embora simples de criar, é geralmente um pouco desorganizado e tedioso de implementar.

Code Igniter provê uma estrutura detalhada de validação que de fato minimiza a quantidade de linhas de código que você teria de escrever. Também remove toda as estruturas de controle de seu HTML, permitindo que seja limpo e livre de código.

Visão Geral

De modo a implementar a validação de formulário do Code Igniter você precisará de três coisas:

  1. Um arquivo de View contendo o formulário.
  2. Um arquivo de View contendo a mensagem de "successo" para ser exibida após o formulário ser enviado.
  3. Uma função controller para receber e processar os dados que forem submetidos pelo formulário.

Vamos criar estas três coisas usando como exemplo um formulário de cadastro de usuário.

O Formulário

Usando um editor de texto, crie um formulário chamado myform.php. Nele coloque este código e salve-o na sua pasta applications/views/:

A Página de Sucesso

Usando um editor de texto, crie um formulário chamado formsuccess.php. Nele coloque este código e salve-o na sua pasta applications/views/:

O Controller

Usando um editor de texto, crie um formulário chamado form.php. Nele coloque este código e salve-o na sua pasta applications/controllers/:

Execute-o!

Para executar seu formulário, visite seu site usando uma URL similar a esta:

www.seu-site.com/index.php/form/

Se você enviar o formulário verá apenas ele ser recarregado. Isso porque você ainda não configurou regras de validação, regras estas que em breve veremos.

Explanação

Você perceberá muitas coisas a respeito das páginas acima:

O formulário (myform.php) é um formulário padrão, com algumas exceções:

  1. Ele usa um assistente de formulário para criar a abertura do formulário. Tecnicamente isto não é necessário. Você poderia criar o formulário usando um HTML padrão. Entretando, o benfício de usar um assistente é que ele gera a URL de 'action' para você, baseado na URL em seu arquivo de configuração. Isto torna sua aplicação mais portável e flexível na eventualidade de mudança de suas URLs.
  2. No topo do formulário você notará a seguinte variável: <?=$this->validation->error_string; ?>

    Esta variável exibrá qualquer mesagem de erro retornada pelo validador. Se não existirem mensagens, ele não retornará nada.

O controller (form.php) tem uma função: index(). Esta função inicializa a classe de validação e carrega o assistente de formulário e o assistente de URL usados pelos seus arquivos de view. Ela também executa a rotina de validação. No caso da validação ter sido bem sucedida, pode ser apresentado o formulário ou a página de sucesso de envio.

Partindo do pressuposto que você não tenha dito à classe de validação para validar coisa alguma ela retornará "false"(false booleano) por padrão. A função run() apenas retorna "true" se tiver aplicado suas regras com sucesso sem nenhum tipo de falha.

Configurando Regras de Validação

Code Igniter permite que você configure quantas regras você precisar para determinado campo, cascateando-as em ordem, e permite até mesmo que você trate e pré-processe os datos do campo concomitantemente. Vejamos isso em ação, explicaremos isso em seguida.

Em seu controller (form.php), adicione este código logo abaixo da função de inicialização de validação:

$rules['username'] = "required";
$rules['password'] = "required";
$rules['passconf'] = "required";
$rules['email'] = "required";

$this->validation->set_rules($rules);

Seu controller agora irá se parecer com algo assim:

Agora submeta o formulário com os campos em branco e você deverá ver a mensagem de erro. Se você submeter o formulário com todos os campos preenchidos, verá então a página de envio com sucesso.

Nota: Os campos do formulário ainda não estão sendo re-populados com os dados quando ocorre o erro. Vamos chegar nesta parte em breve, uma vez que ainda estamos falando sobre as regras de validação.

Alterando os Delimitadores de Erro

Por padrão, o sistema adiciona uma tag de parágrafo (<p>) em volta de cada mensagem de erro exibida. Você pode facilmente alterar estes delimitadores com este código, colocado em seu controller:

$this->validation->set_error_delimiters('<div class="error">', '</div>');

Neste exemplo nós trocamos para tags DIV.

Regras em Cascata

Code Igniter permite concatenar múltiplas regras. Vamos experimentar. Altere sua array de regras para isto:

$rules['username'] = "required|min_length[5]|max_length[12]";
$rules['password'] = "required|matches[passconf]";
$rules['passconf'] = "required";
$rules['email'] = "required|valid_email";

O código acima requer que:

  1. O campo username não seja menor que 5 caracteres nem maior que 12.
  2. O valor do campo senha(password) deve corresponder ao valor do campo de confirmação de senha (passconf).
  3. O campo email deve conter um endereço de email válido.

Experimente

Nota: Há muitas regras disponíveis que você pode ler sobre na referência de validação.

Tratando os Dados

Juntamente com as funções de validação como as que usamos acima, você também pode tratar seus dadoas de vários modos. Por exemplo, você pode configurar regras como esta: $rules['username'] = "trim|required|min_length[5]|max_length[12]|xss_clean";
$rules['password'] = "trim|required|matches[passconf]|md5";
$rules['passconf'] = "trim|required";
$rules['email'] = "trim|required|valid_email";

Acima, estamos "aparando"("trimming") os campos, covertendo o password para MD5, e executando o username através da função "xss_clean", que remove dados maliciosos.

Qualquer função nativa do PHP que aceite um parâmetro pode ser usada como regra, como, por exemplo,: htmlspecialchars, trim, MD5, etc.

Nota: Geralmente você irá querer usar as funções de tratamento depois das regras de validação, pois caso exista algum erro os dados originais serão mostrados no formulário.

Callbacks(Rechamadas): Suas próprias Funções de Validação

O sistema de validação suporta callbacks(rechamadas) para suas próprias funções de validação. Isto permite que você extenda a classe de validação para suas necessidades. Por exemplo, se você precisa executar uma query no banco de dados para ver se o usuário escolheu um nome de usuário(username) único, você pode criar uma função de callback que faça isso. Vamos criar um exemplo simples.

Em seu controller, altere a regra de "username" para isto:

$rules['username'] = "callback_username_check";

Então adicone uma nova função chamada username_check ao seu controller. Aqui está como deve ficar seu controller:

Recarregue seu formulário e submeta a palavra "test" como Nome de usuário(username). Você pode ver que os dados do campo do formulário foram passados a sua função de callback(rechamada) para você processar.

Para chamar um callback apenas coloque o nome da função em uma regra com "callback_" como prefixo da regra.

A mensagem de erro foi configurada usando a função $this->validation->set_message. Lembre-se que a chave da mensagem (o primeiro parâmetro) deve coincidir com o nome de sua função.

Nota: Você pode aplicar suas próprias mensagens de erros personalizadas a qualquer regra, apenas configurando a mensagem similarmente. Por exemplo, para alterar a mensagem para a regra "required" (obrigatório) você fará isto:

$this->validation->set_message('required', 'Your custom message here');

Re-populando o formulário

Até aqui estivemos apenas lidando com erros . Chegou a hora de repopular os campos do formulário com os dados enviados. Isto é feito similarmente às regras. Adicione o seguinte código a seu controller, logo abaixo de suas regras:

$fields['username'] = 'Nome de usuário';
$fields['password'] = 'Senha';
$fields['passconf'] = 'Confirmação de Senha';
$fields['email'] = 'Endereço de Email';

$this->validation->set_fields($fields);

As chaves do array são os nomes atuais dos campos do formulário, o valor representa o nome completo que você quer mostrar na mensagem de erro.

A função index de seu controller irá se parecer com algo assim:

Agora abra seu arquivo de view myform.php e atualize o valor em cada campo de modo que cada um tenha um objeto correspondente a seu nome:

Agora recarregue sua página e envie o formulário de modo que isso irá disparar um erro. Seu formulário deverá estar populado e as mensagens de erro conterão um nome de campo mais relevante.

Exibindo Erros Individualmente

Se você preferir mostrar uma mensagem de erro próxima a cada campo do formulário, ao invés de uma lista, você pode alterar seu formulário de modo que ele fique parecido com algo assim:

Se não houverem erros, nada será mostrado. Se houver um erro, a mensagem aparecerá dentro dos delimitadores que você configurou (tag <p> por padrão).

Nota: Para exibir erros desta maneira você deve lembrar de configurar seus campos usando a função$this->validation->set_fields descrita anteriormente. Os erros serão transformados em variáveis que tenham "_error" após o nome do seu campo. Por exemplo , seu erro para "username" estará disponível em:
$this->validation->username_error.

Referência de Regras

O que segue é uma lista de todas as regras nativas que estão disponíveis para uso:

Regra Parâmetro Descrição Exemple
required Não Retorna FALSE se o elemento do formulário estiver vazio.  
matches Sim Retorna FALSE se o elemento do formulário não corresponder com o elemento no parâmetro. matches[form_item]
min_length Sim Retorna FALSE se o elemento do formulário for mais curto/menor que o valor do parâmetro. min_length[6]
max_length Sim Retorna FALSE se o elemento do formulário for mais longo/maior que o valor do parâmetro. max_length[12]
exact_length Sim Retorna FALSE se o elemento do formulário não for exatamente igual ao valor do parâmetro. exact_length[8]
alpha Não Retorna FALSE se o elemento do formulário contiver alguma outra coisa que não sejam caracteres alfabéticos(letras).  
alpha_numeric Não Retorna FALSE se o elemento do formulário contiver alguma outra coisa que não sejam caracteres alfanuméricos.  
alpha_dash Não Retorna FALSE se o elemento do formulário contiver alguma outra coisa que não sejam caracteres alfanuméricos, underscores ou traços(hífen).  
numeric Não Retorna FALSE se o elemento do formulário contiver alguma outra coisa que não sejam caracteres numéricos(números).  
valid_email No Retorna FALSE se o elemento do formulário não contiver um endereço de email válido.  
valid_ip Não Retorna FALSE se o IP fornecido não for válido.  

Nota:Estas regras também podem ser chamadas através de funções discretas. Por exemplo:

$this->validation->required($string);

Nota: Você também pode usar quaisquer funções nativa do PHP que permitam um parâmetro.

Referência de Tratamento de Dados

O que segue é uma lista de todas as funções de tratamento que estão disponíveis para uso:

Nome Parâmetro Descrição
xss_clean Não Executa os dados através da função de filtragem XSS, descrita na página Classe Input.
prep_for_form Não Converte caracteres especiais de modo que dados HTML pode ser mostrados em um campo de formulário sem quebrá-lo.
prep_url Não Adiciona "http://" às URLs caso não tenham.
strip_image_tags Não Retira o código HTML das tags de imagem deixando apenas a URL bruta de endereço da mesma.
encode_php_tags Não Converte tags PHP em 'entities'.

Nota: Você também pode usar quaisquer funções nativa do PHP que permitam um parâmetro, comotrim, htmlspecialchars, urldecode, etc.

Configurando Mensagens de Erros Personalizadas

Todas as mensagens de erro estão localizadas no seguinte arquivo de idioma: language/english/validation_lang.php

Para configurar sua própria mensagem personalizada você pode: ou editar esse arquivo ou usar a seguinte função:

$this->validation->set_message('regra', 'Mensagem de Erro');

Onde regra corresponde ao nome de uma regra particular, e Mensagem de Erro é o texto que deverá ser exibido.

Tratando com Menus Select, Radio Buttons e Checkboxes

Se você usa menus select, radio buttons or checkboxes, irá, então, querer que o estado destes itens seja guardado quando ocorrer um erro. A classe Validação tem três funções que o auxiliam a fazer isto:

set_select()

Permite que vocÊ exiba o item do menu que foi selecionado. O primeiro parâmetro deve conter o nome do menu select, o segundo parâmetro deve conter o valor de cada item. Exemplo:

<select name="meuselect">
<option value="um" <?= $this->validation->set_select('meuselect', 'um'); ?> >Um</option>
<option value="dois" <?= $this->validation->set_select('meuselect', 'dois'); ?> >Dois</option>
<option value="tres" <?= $this->validation->set_select('meuselect', 'tres'); ?> >Três</option>
</select>

set_checkbox()

Permite que você exiba um checkbox no estado em que foi enviado. O primeiro parâmetro deve conter o nome do checkbox, o segundo parâmetro deve conter seu valor. Exemplo:

<input type="checkbox" name="meucheck" value="1" <?= $this->validation->set_checkbox('meucheck', 1); ?> />

set_radio()

Permite que você exiba radio buttons no estado em que forem enviados. O primeiro parâmetro deve conter o nome do radio button, o segundo parâmetro deve conter seu valor. Exemplo:

<input type="radio" name="meuradio" value="1" <?= $this->validation->set_radio('meuradio', 1); ?> />