PHP Yii Framework: Trabalhando com formulários

Um formul�rio HTML � uma se��o de documento que possui elementos especiais (caixa de sele��o, bot�es de r�dio, menus, etc.). Veja na Listagem 1 o exemplo de formul�rio simples.

Listagem 1. Formul�rio em HTML utilizando bot�es de r�dio e bot�es de sele��o.


  <FORM action="index.php" method="post">
      <P>
      <LABEL for="firstname">Primeiro nome: </LABEL>
                <INPUT type="text" id="firstname"><BR>
      <LABEL for="lastname">�ltimo nome: </LABEL>
                <INPUT type="text" id="lastname"><BR>
      <LABEL for="email">Email: </LABEL>
                <INPUT type="text" id="email"><BR>
      <INPUT type="radio" name="sex" value="Masc"> Masculino<BR>
      <INPUT type="radio" name="sex" value="Fem"> Feminino<BR>
      <INPUT type="submit" value="Send"> <INPUT type="reset">
      </P>
   </FORM>

A coleta dos dados fornecidos pelo usu�rio por meio dos formul�rios � uma das principais tarefas que o desenvolvedor web se depara no seu cotidiano. Al�m da cria��o desses formul�rios, os desenvolvedores precisam se certificar que o usu�rio ir� fornecer informa��es com dados ou valores existentes, al�m de validar os campos e exibir, sempre que necess�rio, mensagens de erro para entradas inv�lidas e por fim salvar os dados fornecidos. Ao utilizarmos o Framework Yii iremos notar o quanto nosso trabalho ser� reduzido por sua facilidade de desenvolvimento baseado na arquitetura MVC.

Para se trabalhar com formul�rios em Yii s�o necess�rios tr�s passos:

Crie uma classe modelo que representa os campos de dados a serem coletados;
Crie um controlador de a��o com o c�digo que responde � submiss�o do formul�rio;
Crie um arquivo de vis�o do formul�rio associado com o controlador de a��o.

Criando um Modelo

Antes de criarmos o HTML do formul�rio devemos definir que tipos de dados desejamos que o usu�rio forne�a e quais regras eles devem seguir.

Para registrarmos essas informa��es podemos utilizar uma classe modelo, que segundo a documenta��o do Yii, � o lugar central para manter as informa��es fornecidas pelo usu�rio e valid�-las.

Nossa classe ir� variar de acordo com o prop�sito do sistema: os dados coletados ser�o processados e logo ap�s descartados, ent�o utilizaremos um modelo de formul�rio (form model) onde os dados fornecidos pelo usu�rio devem ser armazenados em um banco de dados. Para todo esse processo devemos utilizar um active record.

Definindo uma Classe Modelo3

Na Listagem 2 criaremos uma classe modelo chamada de LoginForm que utilizaremos para coletar os dados informados pelo usu�rio em uma tela de login. Como usaremos essa informa��o apenas para a autentica��o do usu�rio, sem a necessidade de armazenar essa informa��o em uma base de dados, ent�o criaremos essa classe como um modelo de formul�rio.

Listagem 2. Implementa��o da Classe LoginForm que ser� utilizada para coletar as informa��es fornecidas pelo usu�rio no momento do login.


  class LoginForm extends CFormModel 
  { 
              public $username; 
              public $password; 
              public $rememberMe=false; 
  }

Na listagem acima declaramos tr�s atributos: $username, $password, $rememberMe. Eles ser�o utilizados para armazenar o nome de usu�rio e senha informados no formul�rio, tal como a possibilidade de que o sistema se lembre de seu login. Podemos ver que, por padr�o, a vari�vel $rememberMe recebe false, portanto a op��o correspondente no formul�rio de login estar� desmarcada.

Regras de Valida��o

Ap�s o usu�rio enviar seus dados e os mesmos serem recuperados pelo modelo, devemos ter a certeza de que essas informa��es ser�o validadas antes de serem efetivamente utilizadas. Para isso, definiremos um conjunto de regras que ser�o testadas contra os dados fornecidos. Para isso utilizaremos o m�todo rules(), que deve retornar um array contendo as informa��es de regras, como mostra a Listagem 3.

Listagem 3. Implementa��o dos m�todos rules() e authenticate.


  class LoginForm extends CFormModel 
  { 
              public $username; 
              public $password; 
              public $rememberMe=false; 
              
              public function rules() 
              { 
                          return array( 
                                     array('username, password', 'required'), 
                                     array('password', 'authenticate'), 
                          ); 
              } 
              public function authenticate($attribute,$params) 
              { 
                          if(!$this->hasErrors()) 
                          // devemos autenticar o usu�rio somente se n�o existir erros de valida��o 
                          { 
                                     $identity=new UserIdentity($this->username,$this->password); 
                                     if($identity->authenticate()) 
                                     { 
                                                 $duration=$this->rememberMe ? 3600*24*15 : 0; // 15 dias 
                                                 Yii::app()->user->login($identity,$duration); 
                                     } 
                                     else 
                                                 $this->addError('password','Senha Incorreta.'); 
                          } 
              } 
  }

Na listagem especificamos que o password e o username s�o obrigat�rios (require). Al�m disso, informamos que password deve ser autenticado (authenticate).

As regras retornadas pelo m�todo rules() devem seguir o formato apresentado pela Listagem 4.

Listagem 4. Formato que o m�todo rules() deve seguir.

array('Atributos', 'Validador', 'on'=>'ListaDeCenarios', ...op��es adicionais)

Os Atributos devem ser uma string contendo todos, separados por v�rgula, que devem ser validados de acordo com a regra. O validador define que tipo de valida��o dever� ser efetuada, onde o par�metro on � opcional e � utilizado para especificar os cen�rios onde a regra deve ser aplicada.

Existem algumas maneiras de especificar o validador em uma regra. Numa delas, o validador pode ser um m�todo na classe do modelo, como o authenticate da Listagem 4. Observe a Listagem 5.

Listagem 5. Assinatura do m�todo validador.


/** 
 * @param string o nome do atributo a ser validado 
 * @param array op��es especificadas na regra de valida��o 
 */ 
public function nomeDoValidador($atributo,$parametros) { ... }

Outra maneira � quando o validador pode ser o nome de uma classe validadora. Dessa forma, quando uma regra � aplicada, uma inst�ncia dessa classe ser� criada para efetuar a valida��o. A classe validadora deve estender a classe CValidator.

Uma terceira maneira � quando o validador pode ser um apelido (alias) pr�-definido para uma classe validadora. No exemplo da Listagem 4, o nome require funcionou como um apelido (alias) para a classe CRequireValidator, que valida se o valor do atributo n�o estiver vazio. Abaixo veremos uma lista completa dos apelidos (aliases) predefinidos:

boolean: apelido para CBooleanValidator, garantindo que o valor de um atributo seja somente CBooleanValidator::trueValue ou CBooleanValidator::falseValue;
captcha: apelido para CCapthcaValidator, garantindo que o atributo � igual ao c�digo de verifica��o exibido em um CAPTCHA;
compare: apelido para CCompareValidator, garantindo que o atributo � igual a outro atributo ou a uma constante;
email: apelido para CEmailValidator, garantindo que o atributo � um endere�o de email v�lido;
default: apelido para CDefaultValueValidator, utilizado para atribuir um valor padr�o (default) aos atributos especificados;
exist: apelido para CExistValidator, garantindo que o valor do atributo existe na coluna da tabela informada;
file: apelido para CFileValidator, garantindo que o atributo cont�m o nome de um arquivo enviado via upload;
filter: apelido para CFilterValidator que modifica o atributo com um filtro;
in: apelido para CRangeValidator, garantindo que o dado informado est� entre uma lista espec�fica de valores;
length: apelido para CStringValidator, garantindo que o tamanho do dado est� dentro de um tamanho espec�fico;
match: alias para CRegularExpressionValidator, garantindo que o dado informado casa com um express�o regular;
numerical: apelido para CNumberValidator, garantindo que o dado informado � um n�mero v�lido;
required: apelido para CRequiredValidator, garantindo que o valor do atributo n�o est� vazio.
type: apelido para CTypeValidator, garantindo que o atributo � de um tipo espec�fico.
unique: apelido para CUniqueValidator, garantindo que o dado informado � �nico na coluna da tabela do banco de dados informada.

Veja alguns exemplos de validadores predefinidos na Listagem 6.

Listagem 6. Exemplos de validadores predefinidos.


              // username � obrigat�rio 
              array('username', 'required'), 
              
              // username deve ter entre 5 e 12 caracteres 
              array('username', 'length', 'min'=>5, 'max'=>12), 
              
              // quando estiver no cen�rio register, password deve ser igual password2 
              array('password', 'compare', 'compareAttribute'=>'password2', 
              'on'=>'register'), 
              
              // quando estiver no cen�rio login, password deve ser autenticado 
              array('password', 'authenticate', 'on'=>'login'),

Atribui��o Segura de Atributos

A atribui��o de atributos baseada em cen�rios est� dispon�vel a partir da vers�o 1.0.2 do framework.

Depois que uma inst�ncia da classe modelo � criada, � necess�rio popular seus atributos com as informa��es enviadas pelo usu�rio no ato do login. Isso pode ser feito utilizando a atribui��o em massa, como pode ser visto na Listagem 7.

Listagem 7. Exemplo de atribui��o em massa.


  $model=new LoginForm; 
  $model->scenario='login'; 
  if(isset($_POST['LoginForm'])) 
              $model->attributes=$_POST['LoginForm'];

Nota: A propriedade scenario est� dispon�vel a partir da vers�o 1.0.4. A atribui��o em massa ir� utilizar o valor dessa propriedade para determinar quais atributos devem ser atribu�dos dessa maneira. Nas vers�es 1.0.2 e 1.0.3, para fazer a atribui��o em massa em um cen�rio espec�fico, dever�amos proceder da seguinte maneira:

$model->setAttributes($_POST['LoginForm'], 'login');

Disparando a Valida��o

Uma vez que o modelo tenha recuperado os dados enviados pelo usu�rio, podemos executar o m�todo CModel::validate() que dispara o processo de valida��o. Esse m�todo ir� retornar um valor indicando o sucesso ou n�o da valida��o.

Ao chamarmos o CModel::validate(), temos a op��o de especificar um par�metro com o nome de um cen�rio. Dessa forma, somente as regras desse cen�rio ser�o aplicadas na valida��o. � importante ressaltar que uma regra s� ser� aplicada a um cen�rio, caso n�o exista a op��o on nela, ou, caso exista, seu valor corresponda ao cen�rio especificado.

O c�digo da Listagem 8 ir� executar a valida��o ao registrar um usu�rio.

Listagem 8. C�digo que executa a valida��o de um usu�rio ao se registrar.


$model->scenario='register'; 
$model->validate();

Se fossem em vers�es anteriores, o c�digo deveria ser o mesmo da Listagem 9.

Listagem 9. Exemplo de como informar o cen�rio nas vers�es 1.0.2 e 1.0.3.

$model->validate('register');

Na classe do modelo de formul�rio devemos declarar as regras de valida��o da mesma forma que o apresentado pela Listagem 10.

Listagem 10. Declara��o das regras de valida��o.


  public function rules() 
  { 
       return array( 
         array('username, password', 'required'), 
         array('password_repeat', 'required', 'on'=>'register'), 
         array('password', 'compare', 'on'=>'register'), 
       ); 
  }

O resultado ser� que a primeira regra ser� aplicada a todos os cen�rios, j� as outras duas ser�o aplicadas somente ao cen�rio register.

Nota: Valida��o baseada em cen�rios est� dispon�vel desde a vers�o 1.0.1.

Recuperando Erros de Valida��o

Para verificar se existe algum erro de valida��o podemos utilizar o m�todo CModel::hasErrors(). Caso exista, podemos utilizar o m�todo CModel::getErrors() para obter as mensagens de erro.

R�tulos de Atributos

Quando criamos um formul�rio, normalmente precisamos exibir um r�tulo para cada campo, que por sua vez ir� indicar ao usu�rio que tipo de informa��o o programa espera que ele informe naquele campo. Embora possamos escrever esses r�tulos na camada de vis�o, torna-se mais flex�vel e conveniente especific�-los diretamente no modelo.

Como padr�o, a classe CModel ir� retornar o nome do atributo como seu r�tulo. No entanto, essa caracter�stica pode ser alterada sobrescrevendo o m�todo attributeLabels(). Como veremos adiante, especificar r�tulos nos modelos nos permite criar formul�rios poderosos de uma maneira bem mais r�pida que o convencional.

Criando uma A��o

Agora que j� estamos com um modelo pronto, devemos come�ar a escrever a l�gica necess�ria para poder manipula-lo. Para isso devemos criar uma a��o no controle onde iremos colocar toda a l�gica. Para o exemplo do login, a Listagem 11� necess�ria.

Listagem 11. C�digo de implementa��o da a��o actionLogin.


  public function actionLogin() 
  { 
              $model=new LoginForm; 
              if(isset($_POST['LoginForm'])) 
              { 
                          // coleta a informa��o inserida pelo usu�rio 
                          $model->attributes=$_POST['LoginForm']; 
                          // valida a entrada do usu�rio e redireciona para a p�gina anterior, caso valide 
                          if($model->validate()) 
                                     $this->redirect(Yii::app()->user->returnUrl); 
              } 
                          // exibe o formul�rio de login 
              $this->render('login',array('model'=>$model)); 
  }

Inicialmente criamos uma inst�ncia de um LoginForm. Se a requisi��o for do tipo POST (indicando que um formul�rio de login foi enviado), populamos o $model com os dados enviados via $_POST['LoginForm']. Logo ap�s, validamos os dados e caso a valida��o ocorra com sucesso, redirecionamos o navegador para a p�gina que requisitou a autentica��o. Caso contr�rio, se a valida��o falhar ou se for o primeiro acesso a essa a��o, renderizamos o conte�do da vis�o 'login', que ser� descrita logo mais.

Dica: Na a��o login, foi utilizada a propriedade Yii::app()->user->returnUrl para pegar a URL da p�gina que necessitou da autentica��o. O componente Yii::app()->user � do tipo CWebUser que representa a sess�o com as informa��es do usu�rio.

Criando um Formul�rio

Iremos escrever uma vis�o para o login, que � algo bem simples. Iniciaremos com uma tag form, cujo atributo action deve ser a URL da a��o do login, descrita anteriormente. Em seguida, iremos inserir os r�tulos e os campos para os atributos declarados na classe LoginForm. Por fim, colocaremos um bot�o de envio (submit) que ir� ser utilizado para enviar o formul�rio. Para a constru��o desse formul�rio iremos necessitar apenas de HTML.

O Yii nos oferece alguns m�todos que facilitam a composi��o da vis�o, dentre eles podemos usar o CHtml::textField() para criar uma caixa de texto, e o CHtml::dropDownList(), para criar uma lista do tipo top-down.

Importante: O interessante de se utilizar esses m�todos do Yii � que eles n�o geram apenas o c�digo HTML. O c�digo da Listagem 12, por exemplo, gera uma caixa de texto que dispara o envio do formul�rio caso seu valor seja alterado pelo usu�rio.

Listagem 12. Exemplo de m�todo Yii para composi��o da vis�o.

CHtml::textField($name,$value,array('submit'=>''));

De outra forma, seria necess�rio escrever um monte de c�digo JavaScript espalhado por todo o nosso programa.

No pr�ximo exemplo utilizaremos a classe CHtml para criar um formul�rio de login. Assumiremos que a vari�vel $model representa uma inst�ncia da classe LoginForm, como mostra Listagem 13.

Listagem 13. Formul�rio de login.


  <div class="form">
  <?php echo CHtml::beginForm(); ?>
              <?php echo CHtml::errorSummary($model); ?>
              <div class="row">
                          <?php echo CHtml::activeLabel($model,'username'); ?>
                          <?php echo CHtml::activeTextField($model,'username') ?>
              </div>
              <div class="row">
                          <?php echo CHtml::activeLabel($model,'password'); ?>
                          <?php echo CHtml::activePasswordField($model,'password') ?>
              </div>
              <div class="row rememberMe">
                          <?php echo CHtml::activeCheckBox($model,'rememberMe'); ?>
                          <?php echo CHtml::activeLabel($model,'rememberMe'); ?>
              </div>
              <div class="row submit">
                          <?php echo CHtml::submitButton('Login'); ?>
              </div>
  <?php echo CHtml::endForm(); ?>
  </div><!-- form →

Se utilizarmos a folha de estilo form.css, fornecido como padr�o pelo script do Yii, o formul�rio assumir� a apar�ncia mostrada nas Figuras 1 e 2.

P�gina de
Login

Figura 1. P�gina de Login

P�gina de
Login com Erros

Figura 2. P�gina de Login com Erros

Objetivando a melhora na cria��o de formul�rios, a partir da vers�o 1.1.1, foi disponibilizado um novo widget chamado CActiveForm. Com ele podemos realizar valida��es de forma consistente e transparente. Utilizando o c�digo do �ltimo exemplo, poder�amos reescreve-lo coo apresentado na Listagem 14.

Listagem 14. Formul�rio utilizando o widget CActiveForm.


  <div class="form">
  <?php $form=$this->beginWidget('CActiveForm'); ?>
              <?php echo $form->errorSummary($model); ?>
              <div class="row">
                          <?php echo $form->label($model,'username'); ?>
                          <?php echo $form->textField($model,'username') ?>
              </div>
              <div class="row">
                          <?php echo $form->label($model,'password'); ?>
                          <?php echo $form->passwordField($model,'password') ?>
              </div>
              <div class="row rememberMe">
                          <?php echo $form->checkBox($model,'rememberMe'); ?>
                          <?php echo $form->label($model,'rememberMe'); ?>
              </div>
              <div class="row submit">
                          <?php echo CHtml::submitButton('Login'); ?>
              </div>
  <?php $this->endWidget(); ?>
  </div><!-- form -->

A coleta de v�rios dados fornecidos ao mesmo tempo pelo usu�rio, ou seja, informa��es vindas de diversas inst�ncias de modelos e o envio de todos de uma �nica vez � conhecido como Entrada Tabular, pois normalmente seus campos ir�o ser apresentados em forma de tabela HTML

Para trabalharmos com esse tipo, inicialmente devemos criar e preencher um vetor de inst�ncias de modelos recuperando as entradas do usu�rio a partir da vari�vel $_POST e atribuindo-as para cada modelo. Quando utilizamos um �nico modelo para entrada, a recupera��o dos dados � feita atrav�s do c�digo da Listagem 15.

Listagem 15. C�digo de implementa��o da actionBatchUpdate().


  public function actionBatchUpdate()
   
  {
   
              // recupera os itens para atualiza��o em lote assumindo que cada item � inst�ncia de um  
              // Item
   
              $items=$this->getItemsToUpdate();
   
              if(isset($_POST['Item']))
   
              {
   
                          $valid=true;
   
                          foreach($items as $i=>$item)
   
                          {
                                     if(isset($_POST['Item'][$i]))
   
                                                 $item->attributes=$_POST['Item'][$i];
   
                                                 $valid=$valid && $item->validate();
                                     }
   
                                     if($valid)
   
                                     // todos os itens s�o validos fa�a determinada a��o
   
                          }
   
                          // exibe a vis�o para coletar as entradas tabulares
   
                          $this->render('batchUpdate',array('items'=>$items));
   
              }

Agora podemos criar a vis�o batchUpdate para retornar os campos em uma tabela HTML, como mostra a Listagem 16.

Listagem 16. Vis�o da batchUpdate.


  <div class="yiiForm">
  <?php echo CHtml::beginForm(); ?>
  <table>
  <tr><th>Name</th><th>Price</th><th>Count</th><th>Description</th></tr>
  <?php foreach($items as $i=>$item): ?>
  <tr>
  <td><?php echo CHtml::activeTextField($item,"[$i]name"); ?></td>
  <td><?php echo CHtml::activeTextField($item,"[$i]price"); ?></td>
  <td><?php echo CHtml::activeTextField($item,"[$i]count"); ?></td>
  <td><?php echo CHtml::activeTextArea($item,"[$i]description"); ?></td>
  </tr>
  <?php endforeach; ?>
  </table>
  <?php echo CHtml::submitButton('Save'); ?>
  <?php echo CHtml::endForm(); ?>
  </div><!-- yiiForm →

Finalizamos assim esse artigo sobre a utiliza��o de formul�rios com o Framework Yii. A partir de agora poderemos trabalhar com essa ferramenta de forma mais consciente e obteremos resultados mais expressivos em menos tempo.

Espero que tenham gostado. Deixe aqui seu coment�rio com d�vidas e sugest�es. At� a pr�xima!

Links

Documenta��o do Yii
http://www.yiiframework.com/doc/guide/1.1/en/form.view

Tecnologias:

Confira outros conte�dos:

Teste unit�rio com PHPUnit

PHP: Strings

PHP: Fun��es

Assista grátis a nossa aula inaugural

Perguntas frequentes

Quem somos?

Por que a programação se tornou a profissão mais promissora da atualidade?

Como faço para começar a estudar?

Em quanto tempo de estudo vou me tornar um programador?

Sim, você pode se tornar um programador e não precisa ter diploma de curso superior!

O que eu irei aprender estudando pela DevMedia?

Principais diferenciais da DevMedia

Qual o investimento financeiro que preciso fazer para me tornar um programador?

Como funciona a forma de pagamento da DevMedia?

Por Luciano Em 2015

Nossos casos de sucesso

Leonardo Carlos

Eu sabia pouqu�ssimas coisas de programa��o antes de come�ar a estudar com voc�s, fui me especializando em v�rias �reas e ferramentas que tinham na plataforma, e com essa bagagem consegui um est�gio logo no in�cio do meu primeiro per�odo na faculdade.

Lucas Rodrigues

Estudo aqui na Dev desde o meio do ano passado! Nesse per�odo a Dev me ajudou a crescer muito aqui no trampo.
Fui o primeiro desenvolvedor contratado pela minha empresa. Hoje eu lidero um time de desenvolvimento!
Minha meta � continuar estudando e praticando para ser um Full-Stack Dev!

Her�clito J�nior

Economizei 3 meses para assinar a plataforma e sendo sincero valeu muito a pena, pois a plataforma � bem intuitiva e muuuuito did�tica a metodologia de ensino. Sinto que estou EVOLUINDO a cada dia. Muito obrigado!

Julio Cablen

Nossa! Plataforma maravilhosa. To amando o curso de desenvolvimento front-end, tinha coisas que eu ainda n�o tinha visto. A did�tica � do jeito que qualquer pessoa consegue aprender. S�rio, to apaixonado, adorando demais.

Joelberth Sena

Adquiri o curso de voc�s e logo percebi que s�o os melhores do Brasil. � um passo a passo incr�vel. S� n�o aprende quem n�o quer. Foi o melhor investimento da minha vida!

Felipe Nunes

Foi um dos melhores investimentos que j� fiz na vida e tenho aprendido bastante com a plataforma. Voc�s est�o fazendo parte da minha jornada nesse mundo da programa��o, irei assinar meu contrato como programador gra�as a plataforma.

Wanderson Oliveira

Comprei a assinatura tem uma semana, aprendi mais do que 4 meses estudando outros cursos. Exerc�cios pr�ticos que n�o tem como n�o aprender, est�o de parab�ns!

Jos� Lucas

Obrigado DevMedia, nunca presenciei uma plataforma de ensino t�o presente na vida acad�mica de seus alunos, parab�ns!

Eduardo Dorneles

Aprendi React na plataforma da DevMedia h� cerca de 1 ano e meio... Hoje estou h� 1 ano empregado trabalhando 100% com React!

Adauto Junior

J� fiz alguns cursos na �rea e nenhum � t�o bom quanto o de voc�s. Estou aprendendo muito, muito obrigado por existirem. Est�o de parab�ns... Espero um dia conseguir um emprego na �rea.

Ver todos os casos de sucesso

PHP Yii Framework: Trabalhando com formul�rios

Veja nesse artigo como trabalhar com formul�rios no PHP Yii Framework. Trabalhar com formul�rios � uma das principais tarefas que um desenvolvedor web se depara e com esse artigo voc� vai entender o quanto o Yii Framework pode ajudar.