PHP Yii: Aplicando ActiveRecord na sua aplica��o

Com o passar dos anos, as linguagens de programaç�o evolu�ram, assim como as formas de modelar e desenvolver software. Novas tecnologias surgem frequentemente no cen�rio do desenvolvimento de software em todas as plataformas, sejam elas Windows, Unix, etc. Junto ao surgimento destas tecnologias, h� tamb�m as grandes corporaç�es, as quais est�o sempre acompanhando esta evoluç�o, transformando o desenvolvimento de aplicaç�es em uma verdadeira corrida tecnol�gica.

O ActiveRecord � uma destas tecnologias de momento, uma nova forma de acessar/manipular informaç�es do banco de dados. Esta forma de desenvolvimento � muito �til para aplicaç�es que n�o possuem regras de neg�cio complexas, ou seja, toda a aç�o de persist�ncia � feita, basicamente, atrav�s de CRUDs (create, read, update, delete).

O conceito de ActiveRecord utiliza o modelo de orientaç�o a objetos relacional (ORM � Object Relational Mapping), onde cada entidade, ou no modelo f�sico tabela, � mapeada e refletida em um objeto. Portanto, cada linha (row) da tabela � �empacotada� e associada a um objeto (wrapped). Poss�veis relacionamentos entre estas tabelas s�o representados como atributos (propriedades) de classe. � dado o nome de tupla � cada inst�ncia de objeto.

A preocupaç�o principal do ActiveRecord � a forma como o dado entra e qual ser� seu comportamento, pois a maioria dos dados ir�o persistir e precisar�o ser gravados na base de dados.

Qualquer alteraç�o aplicada no objeto influencia diretamente na tabela do banco de dados. Por exemplo, ao fazer um update (atualizar) dados de um objeto, seu registro no banco correspondente tamb�m � afetado. Para tratar dados resgatados do banco clara e coerentemente, o ActiveRecord utiliza o paradigma da Orientaç�o a Objetos. No Yii Framework, a classe respons�vel por todo este processo de manipulaç�o dos dados entre objeto e banco � a CActiveRecord.

No ActiveRecord a l�gica de dom�nio e persist�ncia dos dados s�o encapsuladas no mesmo local, normalmente na classe a qual estende a CActiveRecord, no caso do Yii.

Nota: N�o ser� abordado neste texto as vantagens e desvantagens em usar o ActiveRecord, apenas sua aplicaç�o no Yii Framework. Este assunto ser� tema para outro artigo. Para um bom entendimento deste texto faz-se necess�rio conhecimento s�lido em Orientaç�o a Objetos.

Conhecendo a CActiveRecord.

Como foi dito antes, a classe CActiveRecord � a respons�vel por manipular os objetos que posteriormente ser�o acoplados �s tabelas. No Yii Framework todas as classes (models) que usar�o o ActiveRecord devem estender a classe CActiveRecord.

Veja a seguir os principais m�todos e atributos para criar uma aplicaç�o corretamente com o padr�o ActiveRecord. Depois ser� dado um exemplo pr�tico sobre como utilizar alguns destes m�todos/atributos. Para a documentaç�o completa acesse http://www.yiiframework.com/doc/api/1.1/CActiveRecord .

Principais Atributos(propriedades) p�blicos.

db � Este atributo � o respons�vel por alterar/retornar a conex�o default(padr�o) para todas as classes que ser�o estendidas da ActiveRecord.
dbConnection � Retorna a conex�o utilizada pela classe ActiveRecord utilizada no momento.
errors � Retorna os erros gerados para um ou mais atributos
isNewRecord � Retorna um valor booleano, true ou false, indica para a classe base se o formul�rio atual � de update (atualizaç�o) ou create (gravar novo dado).
primaryKey � Retorna a chave prim�ria da tabela.
scenario � Retorna o cen�rio utilizado na classe atual.
validatorList � Retorna todos os validadores declarados no modelo.
validators � Retorna todos os validadores aplicados no cen�rio atual.

Nota: O link a seguir explica mais profundamente o conceito de cen�rio, e como se aplica no Yii Framework. Acesse http://www.yiiframework.com/wiki/266/understanding-scenarios/.

Neste artigo � utilizado a vers�o 1.1 do Yii Framework, at� ent�o, a vers�o est�vel do framework. � poss�vel realizar o download da vers�o 2, embora esta vers�o ainda esteja em fase beta. Acesse http://www.yiiframework.com/download/ para mais informaç�es.

Principais m�todos p�blicos

addError(string $atributo, string $erro) - Adiciona erro para um atributo.
attributeLabels() - Retorna os valores de label pr�-definidos.
attributeNames() - Retorna o nome de todos os atributos.
count(mixed $condicao='', array $paramametros=array( )) - Retorna o n�mero de linhas da consulta executada.
createValidators() - Cria objetos validadores baseado nas especificaç�es definidas nas rules.

Nota: Para mais informaç�es sobre rules acesse http://www.yiiframework.com/wiki/56/ .

delete() - Apaga determinado registro da tabela correspondente ao objeto AcriveRecord.
deleteAll(mixed $condicao='', array $parametros=array ( )) - Apaga todos os registros da tabela de acordo com a condiç�o passada por par�metro.
deleteAllByAttributes(array $atributos, mixed $conditicao='', array $parametros=array ( )) - Apaga todos os registros de acordo com os atributos e valores passados por par�metro.
deleteByPk(mixed $chavePrimaria, mixed $condicao='', array $parametros=array ( )) - Apaga o registro a partir da chave prim�ria (Primary Key) passada por par�metro.
exists(mixed $condicao='', array $parametros=array ( )) - Verifica se a linha correspondente � condiç�o passada existe.
find(mixed $condicao='', array $parametros=array ( )) - Retorna a primeira linha que conferir com a condiç�o passada por par�metro.
findAll(mixed $condicao='', array $parametros=array ( )) - Retorna todas as linhas que conferirem com a condiç�o passada por par�metro.
findAllByAttributes(array $atributos, mixed $condicao='', array $parametros=array ( )) - Retorna todas as linhas de acordo com os atributos e condiç�o passados.
findAllByPk(mixed $chavePrimaria, mixed $condicao='', array $parametros=array ( )) - Retorna todos os registros de acordo com a chave prim�ria e condiç�o passadas.
getAttribute(string $nomeAtributo) � Retorna o atributo passado por par�metro.
model(string $nomeClasse='CActiveRecord') � M�todo est�tico que retorna a inst�ncia da classe ActiveRecord atual.
save(boolean $comValidacao=true, array $atributos=NULL) � Salva os dados do objeto na tabela correspondente.
setAttribute(string $nome, mixed $valor) � Altera os respectivos nomes e valores de um determinado atributo.
update(array $atributos=NULL) � Atualiza os dados do objeto, e consequentemente da tabela.
updateByPk(mixed $chavePrimaria, array $atributos, mixed $condicao='', array $parametros=array ( )) - Atualiza o registro da linha passada pela chave prim�ria.

Exemplo pr�tico

Agora que j� � sabido as principais funcionalidades da classe CactiveRecord vamos a um exemplo pr�tico. Em outro artigo, aqui mesmo na DevMedia, foi explicado a operaç�o de cadastrar dados no banco, diante disso, no exemplo a seguir ser� considerado os dados j� cadastrados no banco. De forma que aqui ser� visto como ler e exibir estes dados na aplicaç�o. Para mais informaç�es acesse https://www.devmedia.com.br/php-yii-framework-trabalhando-com-banco-de-dados-na-pratica/30980 .

Cen�rio da aplicaç�o

O portal de not�cias fict�cio �PortalNews� � um grande jornal, e tem como principal foco noticias sobre esporte. Em sua p�gina s�o exibidas not�cias que possuem: id, autor respons�vel pela publicaç�o, categoria, t�tulo e conte�do. Toda not�cia possui, obrigatoriamente uma, e somente uma categoria. Apenas usu�rios administradores podem publicar not�cias.

Veja nas Figuras 1, 2 e 3 as tabelas de Not�cia, Categoria e Administrador, respectivamente.

Figura 1. Tabela de Not�cias.

Figura 2.Tabela de Categorias.

Figura 3. Tabela de Administradores.

Listando Not�cias

Nota: O Yii Framework, atrav�s do Gii (gerador de models, controllers e m�dulos), cria por padr�o as actions de index e view, onde s�o listados os registros(not�cias) e s�o exibidas informaç�es espec�ficas de um registro(not�cia), respectivamente. Para fins did�ticos, neste exemplo ser�o ignoradas estas actions, sendo assim elas ser�o criadas manualmente. Actions: actionListaNoticias() e actionExibeNoticia().

Criando Action de Not�cias

Agora � hora de colocar em pr�tica algumas utilidades do ActiveRecord, para isso usaremos a funç�o findAll() do Yii Framework. Abra o seu controlador de not�cias e digite o seguinte c�digo da Listagem 1 para criar a actionListaNoticias().

Listagem 1. Criando a action Lista Noticias.


  // Resto do c�digo omitido para melhor visualizaç�o da action criada.
  public function actionListaNoticias(){
              $noticias = Noticia::model()->findAll();
              $this->render('listaNoticias', array(
                          'noticias'=>$noticias,
              ));
  }

Note que o m�todo est�tico model() tem a funç�o de retornar a inst�ncia da classe, sem a necessidade de criar um novo objeto separadamente.

Depois de criada a Action � necess�rio configurar no controlador quais ser�o as restriç�es desta nova action criada, isto � feito atrav�s da funç�o rules(), j� citada antes. Neste caso a p�gina de visualizaç�o de not�cias ser� p�blica, isto �, vis�vel a todos os n�veis de usu�rio. Veja na Listagem 2 como ficar� a rules() implementada com as novas regras de restriç�o.

Listagem 2. Acrescentando regra da action Criada.


  // C�digo omitido para melhor visualizaç�o.
  public function accessRules(){
              return array(
                          //ALTERAÇ�O SER� FEITA AQUI, PARAMETRO �ACTIONS�
                          array('allow',  // allow all users to perform 'index' and 'view' actions
                                     'actions'=>array('index','view', 'listaNoticias'),
                                     'users'=>array('*'),
                          ),
                          // FIM DA ALTERAÇ�O
                          array('allow', // allow authenticated user to perform 'create' and 'update' actions
                                     'actions'=>array('create','update'),
                                     'users'=>array('@'),
                          ),
                          array('allow', // allow admin user to perform 'admin' and 'delete' actions
                                     'actions'=>array('admin','delete'),
                                     'users'=>array('admin'),
                          ),
                          array('deny',  // deny all users
                                     'users'=>array('*'),
                          ),
              );
  }

Criaç�o da View de Not�cias

A estrutura dos dados no banco est� pronta, agora � hora de renderizarmos as informaç�es advindas do banco de dados. � a� que entra o papel da view, vamos cri�-las.

Acesse sua pasta views, a qual se situa em protected/views/noticia, e dentro dela crie o arquivo listaNoticias.php. Digite o c�digo da Listagem 3 em sua view.

Listagem 3. Exibindo dados na View.


  <?php for ($i=0; $i < count($noticias); $i++):?>
  <div>
              <h3>
                          <?php echo $noticias[$i]['titulo']; ?>
              </h3>
  </div>
  <div>
              <p>
                          <?php echo $noticias[$i]['conteudo']; ?>
              </p>
              <small>
                          Classificado como: 
                          <?php // Dados relacionados no banco de dados ?>
                          <?php echo $noticias[$i]->idCategoria0['nome']; ?>
              </small>
  </div>
  <div align="right">
              <small>
                          Postado em:
                          <?php echo $noticias[$i]['data']; ?>
              </small>
  </div>
  <?php endfor; ?>

A partir deste momento, se tudo estiver ocorrido de forma correta, a sua p�gina de Not�cias ser� semelhante � Figura 4.

Figura 4. P�gina de exibiç�o de Not�cias.

P�gina espec�fica de cada not�cia

O �Portal News� esta quase pronto, algumas funcionalidades bastante interessantes est�o funcionando bem. Entretanto, como todo bom portal de not�cias, o �Portal News� tamb�m possui uma p�gina espec�fica para cada not�cia cadastrada.

Action Exibe Noticia

Ainda no controlador Noticia, crie a actionExibeNoticia(), note que ela receber� por par�metro o id da not�cia requisitada. Confira na Listagem 4.

Listagem 4. Criando action Exibe Noticia.


  // C�digo omitido acima para facilitar o entendimento.
  public function actionExibeNoticia($id){
              $noticia = Noticia::model()->find('id='.$id);
              $this->render('exibeNoticia', array(
                          'noticia'=>$noticia,
              ));
  }

N�o esqueça de alterar as restriç�es de visualizaç�o da action criada. Confira na Listagem 5.

Listagem 5. Alterando permiss�es da action Exibe Noticia.


  public function accessRules(){
              return array(
                          // ALTERAÇ�O AQUI!
                          array('allow',  // allow all users to perform 'index' and 'view' actions
                                     'actions'=>array('index','view', 'listaNoticias', 'exibeNoticia'),
                                     'users'=>array('*'),
                          ),
                          // FIM DA ALTERACAO
                          array('allow', // allow authenticated user to perform 'create' and 'update' actions
                                     'actions'=>array('create','update'),
                                     'users'=>array('@'),
                          ),
                          array('allow', // allow admin user to perform 'admin' and 'delete' actions
                                     'actions'=>array('admin','delete'),
                                     'users'=>array('admin'),
                          ),
                          array('deny',  // deny all users
                                     'users'=>array('*'),
                          ),
              );
  }

View Exibe Noticia

Dentro do diret�rio �protected/views/noticia� crie o arquivo(view) exibeNoticia.php e preencha-o com o seguinte c�digo da Listagem 6.

Listagem 6. Construç�o da View respons�vel por exibir a not�cia.


  <div>
              <h3>
                          <?php echo $noticia['titulo']; ?>
              </h3>
  </div>
  <div>
              <p>
                          <?php echo $noticia['conteudo']; ?>
              </p>
              <small>
                          Classificado como: 
                          <?php echo $noticia->idCategoria0['nome']; ?>
              </small>          
  </div>
  <div align="right">
              <small>
                          Postado em: 
                          <?php echo $noticia['data']; ?>
              </small>
  </div>

Se tudo ocorreu conforme o esperado, a p�gina de exibiç�o de not�cia ser� semelhante � Figura 5.

Figura 5. P�gina da Noticia.

Neste texto foi explicado os principais conceitos de um padr�o de projeto ActiveRecord, al�m de um exemplo pr�tico onde este padr�o foi implementado no Yii Framework. Como dito antes, o assunto ActiveRecord � demasiadamente extenso, por isso foi passada apenas uma vis�o superficial dele. Este tema ser� tratado nos pr�ximos artigos.

At� a pr�xima!