Esta é uma tradução de uma série de artigos intitulados "Learning the Yii Framework", originalmente escritos em Inglês e publicados por Larry Ullman.

Introdução ao Framework YiiA primeira coisa que você precisa para usar o framework Yii é acesso a um servidor Web com PHP instalado, claro. Mas se você está lendo isso, vou assumir que você tem acesso a um servidor PHP. Note que o framework Yii requer PHP 5.1 ou superior. Felizmente, o framework irá testar a configuração para você! Comece fazendo o download da última versão estável do Framework Yii. No momento da redação deste texto, é a 1.1.4. O arquivo terá um nome como yii-version.release.ext e tem apenas cerca de 2MB. Extraia o conteúdo do arquivo baixado para criar uma pasta com:

• documentos de texto CHANGELOG, LICENSE, README, e UPGRADE

• pasta demos

• pasta framework

• pasta requirements

Você deve ler os documentos README e LICENSE, é claro, mas as pastas são mais importantes aqui. A pasta demos contém quatro aplicações web escritas usando Yii: um blog, o jogo de forca, um "Olá Mundo!" básico e uma agenda de telefones. As demos são ótimas para ver código funcional enquanto você está tentando escrever o seu próprio. A pasta framework é o que é exigido por qualquer site usando Yii. A pasta de requirements é algo simples e brilhante...

Presumo também que você já sabe qual é o diretório raiz da Web em seu computador ou servidor: esta é a pasta para onde a URL aponta. Em outras palavras, quando você vai para http://localhost ou http://www.example.com em seu navegador, ele recebe os documentos da pasta raiz da Web. Seguindo as convenções do Yii, eu vou chamar esta de WebRoot. Crie uma nova pasta em seu WebRoot chamada yii, e copie as pastas framework e requirements para lá. Então vá para yourURL /yii/requirements em seu navegador da Web (por exemplo: http://localhost/yii/requirements). Você deverá ver um relatório informado se a sua instalação atende aos requisitos mínimos ou não.

Assumindo que sua configuração passou em todos os requisitos, você está apto para seguir em frente. Note que você não precisa necessariamente de todas as extensões: você só precisa realmente dos requisitos do framework Yii, PDO, e a extensão PDO do banco de dados que você vai usar. (Se você não está familiarizado com ele, PDO é uma camada de abstração de banco de dados, fazendo com que os sites sejam agnósticos ao banco de dados.)

No próximo capítulo, vou mostrar-lhe como usar as ferramentas de linha de comando do Yii para criar a sua primeira aplicação web. É uma coisa muito fácil e é a coisa mais próxima de Ruby on Rails que eu já vi (o que eu considero uma coisa muito boa). Capítulos posteriores irão orientá-lo no desenvolvimento de uma aplicação baseada no Yii.

Iniciando com o Framework YiiPara o exemplo específico, eu vou usar um aplicativo Web, com uma lista de departamentos e uma lista de empregados, cada empregado estando em apenas um departamento. Este é um exemplo fácil de entender, prático, usa mais de uma tabela de banco de dados, e é extensível de muitas maneiras. Para começar, você vai usar as ferramentas de linha de comando de Yii para criar a estrutura do aplicativo. Se você vai colocar o site em um servidor onde não tem acesso a linha de comando, você deve instalar um servidor Web completo (Apache, PHP, MySQL, etc) em seu computador, executar essas etapas, e em seguida, fazer o upload do projeto finalizado. Se você ainda não tem um servidor Web no seu computador, eu recomendo usar o XAMPP (para Windows) ou MAMP (para Mac),

pois ambos são gratuitos e extremamente fáceis de usar.

A primeira coisa que você precisa fazer é certificar-se de que você tem a versão mais recente do framework Yii. Então você vai querer colocar a pasta do framework em um local adequado no servidor. Você não precisa colocá-lo dentro do diretório Web (sem dúvida, você não deveria), mas nas proximidades, como no diretório do exemplo abaixo. Por exemplo, na minha configuração, a pasta htdocs é a raiz da Web, o que quer dizer que http://www.example.com aponta para lá.

Dica: Se você vai usar o Yii para vários sites no mesmo servidor, coloque a pasta do framework em uma estrutura lógica de diretório relativa a cada site. Dessa forma, quando você atualizar o framework, você só precisa substituir os arquivos em um só lugar.

Em seguida, você vai precisar acessar a linha de comando, como uma janela do DOS / console no Windows ou o aplicativo Terminal no Mac OS X (e algumas versões do Linux). Em seguida, vá para o diretório do framework. No meu servidor, isso significa executar esta linha:

cd /Users/larryullman/Sites/YiiBlogSite/framework

Você vai precisar mudar os dados para corresponder à sua configuração.

O próximo passo é informar ao aplicativo yiic, encontrado na pasta framework, para criar um novo site. A sintaxe é

yiic webapp path/to/directory

Mas antes mesmo de começar a usar este comando, deixe-me explicar um pouco, porque é muito importante e pode ser complicado. O arquivo yiic é um executável que é executado usando PHP de linha de comando do computador e que realmente só chama o script yiic.php. Você pode chamá-lo usando apenas yiic ou usando ./yiic (ou seja, executar o comando yiic encontrado no diretório atual). Ou você pode chamar mais explicitamente usando php yiic ou php yiic.php. Ou você pode precisar para indicar o executável do PHP ser usado: C:\php\php.exe yiic. Você deve tentar as variações sobre este comando, conforme o seu computador, apenas para ter certeza de que você pode invocar o yiic, antes de tentar criar o aplicativo Web.

Além de executar corretamente o script yiic, outra pegadinha pode surgir se você tiver mais de uma versão do PHP instalada no seu computador. Para confirmar a versão que está sendo usada, execute o comando php -v (de novo, você pode precisar fornecer o caminho completo para o executável do PHP). No Mac OS X e Unix, você pode usar o which php para revelar o executável do PHP sendo usado pelo comando php. Estes passos podem ajudar a resolver problemas confusos. Por exemplo, no meu Mac, eu uso o MAMP Pro para desenvolvimento Web com PHP e MySQL, mas quando eu executo o PHP através da linha de comando, eu vou realmente invocar o PHP instalado com o sistema operacional. Isso pode ser um problema, como as diferentes versões do PHP podem ou não atender aos requisitos descritos no Yii. Eu sei que quando eu tentei isso, o PHP de linha de comando

(instalado com o sistema operacional) não suporta a extensão PDO necessária, mesmo que a versão Web do PHP (em MAMP Pro) suportasse. Minha solução foi explicitamente nomear o meu executável PHP do MAMP ao executar yiic: /Applications/MAMP/bin/php5.3/bin/php yiic.

Depois de saber que você descobriu a sintaxe apropriada para invocar yiic, você adiciona webapp, que é o comando para "criar um novo aplicativo Web". Acrescente o caminho para o aplicativo Web em si. Dada a estrutura de diretório já indicada (na figura acima), o comando seria apenas

./yiic webapp ../htdocs

ou

php yiic webapp ../htdocs

Ou qualquer variação que você precise para usar.

Você será solicitado a confirmar se deseja criar um aplicativo Web no diretório informado. Digite Y (ou Yes) e pressione Enter. Depois de várias linhas de informações, você deve ver uma mensagem dizendo que o aplicativo foi criado com sucesso. Para confirmar isso, carregar o site no seu navegador (informado a URL adequada, é claro):

Quanto à funcionalidades, o aplicativo gerado já inclui:

• uma primeira página com informações adicionais

• um formulário de contato, com CAPTCHA

• um formulário de login

• a capacidade de saudar um usuário logado por nome

• funcionalidade de logout

É um começo muito bom para uma aplicação, especialmente considerando que você ainda não escreveu uma linha de código. Note que o formulário de contato só irá funcionar após você editar a configuração para fornecer seu endereço de e-mail. Para o login, você pode usar (usuário/senha): demo/demo ou admin/admin. Por fim, a aparência exata da aplicação pode variar de uma versão do framework Yii para outra.

Em termos de arquivos no servidor, dentro do diretório do aplicativo (htdocs, para mim), você vai encontrar:

• assets

• css

• images

• index-test.php

• index.php

• protected

• themes

A pasta assets será utilizada pelo framework Yii principalmente para integração com jQuery (framework JavaScript). As pastas css e images são óbvias. Todo o site também será executado através de um dos dois arquivos de índice (index.php, index-test.php). A pasta protected é realmente a mais importante: você vai editar o código encontrado na pasta para alterar a aparência e comportamento do site. E themes permite criar variações sobre o template do site, assim como temas de um blog WordPress.

Dica: A pasta assets deve ter permissão de escrita para o servidor Web, ou então erros estranhos irão ocorrer. Este não deve ser um problema a menos que você transfira um site Yii de um servidor para outro, e as permissões não estejam corretas, após o processo.

Então esse é o início de uma aplicação Web baseada no Yii. Para cada site que você criar usando o Yii, você provavelmente vai passar por essas etapas. No próximo capítulo, eu vou começar a demonstrar como você pode configurar o aplicativo, e alterá-lo para um exemplo com empregados e departamentos.

Configurando o YiiHá algumas maneiras de configurar como sua aplicação Yii se comporta. Para a maioria, você vai fazer isso através do arquivo protected/config/main.php, mas primeiro eu quero falar sobre o arquivo index.php, criado no seu diretório raiz do aplicativo web. Este é um arquivo de "arranque" (bootstrap), o que significa que todas as interações com o usuário, na verdade, passarão por ele. Por exemplo, mostrar um registro de funcionário pode ser através da URL www.example.com/index.php/employee/show/id/34 e atualizar um registro de departamento pode envolver enviar um formulário para www.example.com/index.php/department/update/id/3. Ambas URLs solicitam apenas um script PHP.

O arquivo index.php é gerado quando você usa o script de linha de comando yiic. Há apenas sete linhas de código não comentadas nele. A primeira identifica a localização do framework Yii:

$yii=dirname(__FILE__).'/../framework/yii.php';

O caminho indicado já deve estar correto (porque ele é criado quando o framework é usado para criar a aplicação), mas você pode alterar esse valor se você mover o framework ou o arquivo de índice.

A segunda linha identifica onde o arquivo de configuração está:

$config=dirname(__FILE__).'/protected/config/main.php';

O comportamento padrão é colocar o diretório protected, onde todos os arquivos do aplicativo residem, no mesmo diretório que o arquivo de índice. Minha inclinação é movê-lo para fora do diretório da Web, assim:

Nesse caso, eu edito o meu arquivo index.php para termos:

$config= '../protected/config/main.php';

Note-se que é perfeitamente razoável mover a localização dos arquivos de sua aplicação (ou seja, a pasta protected), mas você não deve alterar os nomes ou a estrutura das pastas encontradas dentro do diretório protected.

Dica: Mover a pasta protected para fora do diretório raiz da Web é apenas uma precaução de segurança extra. Não é necessário, e você pode não querer se preocupar com a mudança, especialmente enquanto você está apenas começando.

A próxima linha de código liga o modo de depuração:

defined('YII_DEBUG') or define('YII_DEBUG',true);

Você vai querer a depuração ativada no desenvolvimento de um site, mas desativado, uma vez em produção. Para desativar a depuração, remover ou comentar essa linha. Eu normalmente apenas comento-a, para que eu possa reativar a depuração mais tarde. Ou você pode alterá-la para algo como isso, de modo que você pode adicionar a depuração para uma página sob demanda:

if (isset($_GET['debug'])) define('YII_DEBUG', true);

Se você fizer isso, então para depurar qualquer página sob demanda, altere a URL, por exemplo, www.example.com/index.php/site/contact para www.example.com/index.php/site/contact/debug/true.

A próxima linha de código determina quantos níveis da "pilha de chamadas" (call stack) são mostrados em uma mensagem de log:

defined('YII_TRACE_LEVEL') or define('YII_TRACE_LEVEL',3);

A "pilha de chamadas" é uma história de que arquivos, funções, etc, estão incluídos, chamadas, e assim por diante. Com um framework, o carregamento simples da página inicial poderia facilmente envolver uma dezena de ações. A fim de limitar os dados registrados (isto é, logados) com as informações mais recentes, úteis, a pilha de chamadas é limitada pela linha a apenas as últimas três ações.

As duas últimas linhas do arquivo de inicialização incluem o framework e iniciam o aplicativo. Não mexa com estas!

require_once($yii);Yii::createWebApplication($config)->run();

E isso é realmente tudo o que há a fazer na página index.php. A partir do Yii 1.1, o framework cria outro arquivo bootstrap: index-test.php. É exatamente o mesmo que o index.php, exceto que o index-test.php inclui um arquivo de configuração diferente: /protected/config/test.php em vez de /protected/config/main.php. No entanto, o arquivo de configuração de teste inclui apenas o arquivo de configuração principal, em seguida, também habilita o componente CDbFixtureManager, que é usado para testes de unidade. O arquivo index-test.php também omite a limitação da pilha de chamadas.

A maior parte da configuração ocorre no arquivo de configuração main.php, encontrado dentro do diretório protected/config (veja a imagem acima). Há também um arquivo de configuração console.php, mas isso é para uma versão de linha de comando da aplicação. Eu não vou discutir isso aqui, mas você irá editá-lo se você tiver scripts de linha de comando associados com o aplicativo.

O arquivo de configuração retorna um array multi-dimensional de informações, algumas das quais são pré-definidas. Você precisa ter certeza de que a sintaxe apropriada é mantida ao editar este arquivo, então tome cuidado na correspondência parênteses e vírgulas onde for necessário.

Para começar, você vai querer mudar o nome do aplicativo, que é usado no layout HTML padrão, em títulos da página, e assim por diante:

'name'=>'Wicked Cool Yii Site',

Em seguida, na seção modules do array retornado, você deve habilitar o Gii. Gii é uma ferramenta Web que você vai usar para gerar Models (Modelos), Views (Visões) e Controllers (Controladores) para a aplicação. Para habilitar o Gii, basta remover as tags de comentário /* e */ que envolvem este código:

'gii'=>array( 'class'=>'system.gii.GiiModule', 'password'=>'SECURE',),

Também introduza uma senha segura no código, uma que só você saberá.

Dica: o Gii foi adicionado ao Yii na versão 1.1.2, e substitui a funcionalidade disponível usando as ferramentas de linha de comando do Yii.

Seguindo no arquivo, na seção components do array retornado, você provavelmente vai querer habilitar o urlManager. Basta remover os códigos de comentário que envolvem o seguinte:

'urlManager'=>array( 'urlFormat'=>'path',

'rules'=>array( '<controller:w+>/<id:d+>'=>'<controller>/view', '<controller:w+>/<action:w+>/<id:d+>'=>'<controller>/<action>', '<controller:w+>/<action:w+>'=>'<controller>/<action>', ),),

Este componente muda as URLs para serem mais amigáveis para Search Engines e usuários. Por exemplo, a URL padrão para uma página poderia ser algo como www.example.com/index.php?r=site/contact, mas o urlManager vai transformar isso em www.example.com/index.php/site/contact. Se você quiser ir mais longe, é possível configurar o urlManager, juntamente com um arquivo .htaccess do Apache, de modo que index.php não precisa mais ser parte da URL.

Em seguida, você quase sempre vai querer estabelecer a conexão de banco de dados (a menos que você não esteja usando um banco de dados, é claro). Para isso, retornar um array que inclui uma connection string, um nome de usuário e uma senha. Por padrão, uma connection string é pré-definida para o banco de dados SQLite:

'db'=>array( 'connectionString' => 'sqlite:'.dirname(__FILE__).'/../data/testdrive.db',),

Se você estiver usando SQLite, basta alterar o código para que ele aponte para o local do seu banco de dados SQLite. Se você não está usando SQLite, comente ou remova essas três linhas de código.

Se você estiver usando o MySQL, o código apropriado deve ser algo como:

'db'=>array( 'connectionString' => 'mysql:host=localhost;dbname=testdrive', 'emulatePrepare' => true, 'username' => 'username', 'password' => 'password', 'charset' => 'utf8',),

A connection string é um DSN (nome da fonte de banco de dados – Database Source Name), que tem um formato específico. Ela começa com uma palavra-chave que indica o aplicativo de banco de dados a ser utilizado, como mysql, pgsql (PostgreSQL), mssql (Microsoft SQL Server), ou OCI (Oracle). Esta palavra-chave é seguida por dois pontos, então, dependendo da aplicação de banco de dados a ser utilizada, e o ambiente de servidor, um certo número de parâmetros, cada um separado por um ponto e vírgula:

• mysql:host=localhost;dbname=test• mysql:port=8889;dbname=somedb• mysql:unix_socket=/path/to/mysql.sock;dbname=whatever

Indicar a base de dados a ser utilizada é o mais importante. Para mim, quando uso o MAMP no Mac OS X, eu tenho que definir o número da porta, pois não é o padrão esperado (3306). No Mac OS X Server, eu tive que especificar o socket, pois o padrão esperado não estava sendo utilizado lá. Também tenha em mente que você precisa ter as extensões do PHP adequadas instaladas para o banco de dados correspondente, como PDO e PDO MySQL. Você deve, obviamente, mudar os valores do nome de usuário e senha para os valores adequados para o seu banco de dados. Você pode ou não querer mudar o conjunto de caracteres (character set).

Dentro da seção do componente de log, eu habilito o CWebLogRoute. Esta é uma ferramenta de depuração maravilhosamente útil que adiciona toneladas de detalhes a cada página processada. Aqui está o código para o arquivo de configuração:

'log'=>array(

'class'=>'CLogRouter', 'routes'=>array( array( 'class'=>'CFileLogRoute', 'levels'=>'error, warning', ), array ( 'class' => 'CWebLogRoute' ) ),),

E aqui está um exemplo de saída:

Finalmente, no final do arquivo de configuração padrão, você vai encontrar o parâmetro adminEmail. Mude-o para o seu endereço de e-mail, para que você receba mensagens de erro, envios de formulários de contato, etc:

'params'=>array( 'adminEmail'=>'whatever@example.edu',),

Como você pode perceber, edição e adição de componentes é onde muito da configuração ocorre. Os que eu destaquei são apenas os mais imediatamente importantes, na minha opinião, mas certamente há outros, envolvendo cache, segurança, temas e muito mais. Um recurso interessante do Yii é que nem todos os componentes nomeados serão carregados para cada solicitação. Alguns, como os componentes de log são, mas outros são carregados apenas quando necessários, minimizando o impacto no desempenho do uso de muitos componentes.

Um parâmetro a mais de configuração que costumava estar no arquivo de configuração padrão, mas

agora precisa ser adicionado é um indicador do controlador padrão. Em outras palavras, se nenhum controlador está especificado na URL, qual controlador irá ser chamado? Sem configuração adicional, o "site" controller será o padrão. Para mudar isso para um controlador diferente, acrescente:

'defaultController' => 'login',

Note que esta linha em particular não vai funcionar imediatamente pois só o controlador site existe no momento. Mas você poderia fazer esta mudança se você tivesse criado um arquivo protected/controllers/LoginController.php (ou se algum outro arquivo controlador existe e você quer que ele seja o padrão). Note também que você deve adicionar esta linha de modo que seja um elemento de nível superior do array retornado (ou seja, ele não vai em qualquer outra seção, é mais fácil adicioná-lo entre os elementos "basePath" e "name", para maior clareza).

E isso é uma introdução rápida de como configurar seu aplicativo Yii. No próximo capítulo, vou discutir um projeto de banco de dados que eu vou usar nos capítulos posteriores. Depois disso, eu vou te mostrar a mágica: models, views e controllers gerados automaticamente usando ferramentas do Yii.

Definição de bancos de dados para a aplicação YiiO objetivo aqui é criar uma aplicação Web que permitirá você adicionar, editar, visualizar e apagar os departamentos e funcionários de uma empresa hipotética. Essas quatro características são conhecidas como CRUD: Create (ou seja, INSERT), Retrieve (ou seja, SELECT), Update e Delete. Estes quatro atos são a base de todo o sistema de gerenciamento de conteúdo, e outros sistemas de armazenamento de dados. Para conseguir isso, você precisa criar uma série de arquivos para ambos funcionários e departamentos:

Um arquivo de modelo (Model), que define a coisa em si

Um arquivo controlador (Controller), que define as ações que podem ser tomadas com a coisa

Vários arquivos de visão (View), que atuam como a interface do usuário, incluindo formulários para adicionar novos itens e atualizar os já existentes

Com alguns frameworks, fazer tudo isso requer um pouco de trabalho repetitivo: escolher um modelo, copiar, colar, editar, criar novos arquivos, etc, etc. Com o Yii, e com outros frameworks como Ruby on Rails, a maioria do trabalho será feito por você, fazendo a preparação adequada e em seguida, chamando as ferramentas embutidas. Para começar, então, eu preciso pensar sobre os modelos, que serão representados através de tabelas de banco de dados neste exemplo.

As duas tabelas serão bastante simples, com uma relação um-para-muitos entre elas: haverá muitos funcionários em cada departamento, mas cada funcionário será de apenas um departamento. Você pode colocar o que quiser na sua tabela de funcionários, mas para os objetivos do "Aprendendo Yii com Larry Ullman", o que teremos vai ser definido com o comando SQL

CREATE TABLE Employee ( id MEDIUMINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY, departmentId TINYINT UNSIGNED NOT NULL COMMENT "CONSTRAINT FOREIGN KEY (departmentId) REFERENCES Department(id)", firstName VARCHAR(20) NOT NULL, lastName VARCHAR(40) NOT NULL, email VARCHAR(60) NOT NULL, ext SMALLINT UNSIGNED NULL, hireDate TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,

leaveDate DATETIME NULL, INDEX name (lastName, firstName), INDEX (departmentId))

Por convenção é melhor seguir as regras do framework. Por exemplo, eu uso normalmente todas as letras minúsculas e sublinhados para meus nomes de coluna (por exemplo, first_name), mas eu estou usando CamelCase aqui para estar em consonância com o Yii e os padrões gerais de programação orientada a objetos (OOP – Object Oriented Programming) (quando os valores são recuperados para um empregado individual, colunas específicas serão referenciadas usando, por exemplo, $model->firstName). O mesmo vale para a coluna de chave primária, que deve apenas ter o nome id. A coluna departmentId será uma chave estrangeira para a tabela de departamentos, para refletir em qual departamento o empregado está. Vou abordar o comentário adicionado em breve. A coluna ext pretende representar o ramal do telefone do empregado (eu coloquei essa coluna principalmente para demonstrar restrições numéricas no Model). A hireDate é preenchida quando uma linha é inserida (se nenhuma data é fornecida para ela). Note que estou assumindo MySQL aqui, e como se comporta timestamps muda de versão para versão. E há um índice no nome da pessoa para fins de classificação, mais um na coluna departmentID já que ela vai ser usada em associações.

A tabela departamentos contém apenas duas colunas. O primeira é a chave primária, a segunda é o nome do departamento (um índice único é colocado sobre ela).

CREATE TABLE Department ( id TINYINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY, name VARCHAR(40), UNIQUE (name))

Agora, sobre os comentários na tabela de funcionários... o Yii irá reconhecer FOREIGN KEYs que existam e usar essa informação para ajudar a definir o Model. Mas como o MySQL new sempre impõe restrições de chave estrangeira (dependendo da versão do MySQL e do mecanismo de armazenamento utilizado), você pode simular esta restrição para o Yii, adicionando um comentário como aquele associado com a coluna Employee.departmentId. Esse comentário sugere que a coluna do departmentID é uma chave estrangeira que faz referência a coluna id no Model Departament. Se você não adicionar este comentário, não tem problema pois você mesmo pode escrever o código para indicar a relação, mas é bom que o Yii faça isso por você.

Ok, é isso! Depois de ter criado as duas tabelas, você pode voltar para as ferramentas do Yii para criar os modelos, controladores e visões (como eu vou fazer no próximo capítulo). Antes de fazer isso, você deve rever as suas tabelas de banco de dados para se certificar de que elas são exatamente como você quer que elas sejam. Como o Yii irá gerar automaticamente um monte de código para você, todas as mudanças feitas após isso, significa que você vai precisar editar manualmente o código. Então procure acertar ao máximo agora!

Criando modelos, visões e controladores no YiiO Yii, assim como o Ruby on Rails e alguns outros frameworks, tem ferramentas que geram código, arquivos e diretórios para você. Como você pode imaginar, este é um poupador de tempo tremendo. O Yii originalmente oferecia apenas a ferramenta de linha de comando yiic para esta finalidade (também usado para criar o aplicativo Web em si). A partir da versão 1.1.2, há agora a ferramenta web Gii, que roda no navegador. Neste capítulo, vou explicar como usar o Gii para criar os arquivos fundamentais de Modelo, Visão, e Controlador necessários para a aplicação (capítulos posteriores vão cobrir como editar o código gerado automaticamente para atender às suas necessidades).

Nota: Você ainda pode usar o yiic de linha de comando, se você preferir esse ambiente.

Este capítulo demonstra o Gii usando um exemplo de departamentos e empregados, com as duas tabelas de banco de dados já criadas (veja o capítulo anterior). Algumas observações antes:

• Porque o Gii faz parte do trabalho para você, você realmente deve ter seu projeto tão completo quanto possível. Se feito corretamente, depois de criar suas tabelas do banco de dados seguindo os passos seguintes, você não vai usar o Gii novamente para o projeto.

• Você deve habilitar o Gii, usando as instruções do terceiro capítulo.

• Porque o Gii é uma ferramenta poderosa, é melhor não permití-la em um servidor de produção. Idealmente, você vai permitir o Gii em um servidor de desenvolvimento, usá-lo, e desativá-lo, e depois colocar o site em produção.

• Certifique-se de que as duas tabelas de banco de dados existam.

• Certifique-se de que você editou o arquivo de configuração main.php para que a aplicação Yii possa se conectar ao banco de dados. Veja o terceiro capítulo para mais detalhes.

Dica: Para maior segurança, o Gii pode ser configurado para funcionar apenas para um endereço IP específico (ou seja, o seu).

Supondo que você entendeu tudo exposto, e tomou as medidas necessárias, agora você deve carregar o Gii no seu browser. Assumindo que o seu site encontra-se em www.example.com/index.php, a ferramenta Gii está em www.example.com/index.php/gii/. Isso pressupõe que você está usando o componente de gerenciamento de URL no Yii. Se não, vá para www.example.com/index.php?r=gii. Você deve ser levado para a tela de login, onde você deve digitar a senha do Gii (estabelecida no arquivo de configuração) e clique em Enter. Supondo que você digitou a senha correta, você verá uma página inicial e uma lista de opções (com links).

A primeira coisa que você vai querer fazer é gerar os modelos. Clique no link "Model Generator". Na página seguinte:

1. Digite Employee como o nome da tabela (Table Name).

2. Digite Employee como a classe de modelo (Model Class). Você vai perceber que o formulário copia automaticamente o nome da tabela como o nome do modelo.

3. Clique em Preview. Você vai ver uma tabela aparecer na parte inferior do formulário,

indicando os arquivos que serão gerados (apenas um, neste caso).

4. Clique em Generate.

Dica: Para criar um modelo automaticamente para cada tabela do banco de dados, basta digitar * para o nome da tabela.

Você deverá ver uma mensagem indicando que o código foi criado (você pode verificar o novo arquivo para confirmar isso). Se você vir um erro sobre uma incapacidade de gravar o arquivo, você terá que modificar as permissões em protected/models para permitir que o servidor da Web escreva lá. Uma vez que isso funcione para você, repita o processo para a tabela Department.

Estes passos geram os scripts protected/models/Department.php e protected/models/Employee.php, que agora você pode abrir e verificar em seu editor de texto ou IDE. Ao usar a versão 1.1.4 do Yii, o arquivo modelo tinha cerca de 110 linhas de código. Eu vou entrar no código específico em um capítulo posterior, mas você vai ver métodos que definem as regras de validação para o modelo, relações que este modelo tem com os outros, e assim por diante.

Em seguida, e isto é grande, criar as funcionalidades de CRUD. CRUD significa Create, Retrieve, Update e Delete. Em outras palavras, tudo o que você faria com o conteúdo do banco de dados. Clique no link "Crud Generator". Na página seguinte:

1. Digite Employee como a classe Modelo (Model Class).

2. Digite employee como o ID do Controlador (Controller ID). Você vai perceber que o formulário copia automaticamente a classe Modelo, em CamelCase minúsculo, como o ID do controlador (controller ID). Assim, Employee torna-se employee, SomeThing se tornaria someThing.

3. Clique em Preview. Você vai ver uma tabela na parte inferior do formulário, indicando os arquivos a serem gerados.

4. Clique em Generate.

Dica: Se você sabe que não vai precisar de algumas funcionalidades, tais como a capacidade de criar ou excluir um tipo de modelo, desmarque as caixas de seleção correspondentes.

Você deverá ver uma mensagem indicando que o código foi criado. Novamente, se você vir um erro sobre uma incapacidade de gravar o arquivo, você terá que modificar as permissões dos diretórios protected/controllers e protected/views para permitir que o servidor da Web escreva lá. Uma vez que isso funcione para você, repita o processo para o modelo do Departamento (Department Model). A página resultante também vai oferecer um link para ir testar os arquivos gerados.

Este único passo criará o arquivo controlador para cada modelo (DepartmentController.php e

EmployeeController.php), além de um diretório de visões para cada um, com oito arquivos de visão por modelo:

• _form.php

• _search.php

• _view.php

• admin.php

• create.php

• index.php

• update.php

• view.php

O arquivo de formulário é usado tanto para criar, como para atualizar registros. O script de busca (search) é um formulário de busca personalizado. O arquivo _view.php é um template para mostrar um registro individual. O script admin cria uma lista tabular do modelo, com links para as funcionalidades de CRUD. O script index é usado para criar uma lista pública dos registros. O script view é usado para mostrar os detalhes de um registro individual. E os arquivos create e update são cascas (wrappers) para a página de formulário, com títulos apropriados e outras coisas.

Para o Yii 1.0: Em versões anteriores do Yii, antes da 1.1, o arquivo view.php era chamado show.php e o index.php era chamado list.php. Também eram criados menos arquivos de visão.

Nota: Você vai ter situações em que você tem um modelo de alguma coisa, mas não quer a funcionalidade CRUD, então não assuma que você vai sempre efetuar as duas etapas.

Então é isso! Você pode clicar em "logout", clique em "webapp" para voltar à página inicial. Você pode confirmar que o que você fez funcionou verificando os novos diretórios e arquivos ou indo para uma URL. Dependendo se você adicionou o urlManager para a configuração do aplicativo ou não, a URL seria algo como www.example.com/index.php/employee/ ou www.example.com/index.php?r=employee. Você vai ver que não há funcionários ou departamentos na lista e também que você não pode adicionar novos registros sem login (o padrão é admin/admin).

No próximo capítulo, vou discutir a forma de começar a editar o código gerado para fazer a aplicação se comportar mais como você quer ela no mundo real. Mas, graças à ferramenta Gii do Yii, cerca de 80% do trabalho foi feito para você!

Edições básicas nos modelos no YiiO modelo representa os dados usados por um aplicativo. Normalmente, os dados vem de um banco de dados, mas também podem vir de uma submissão de formulário (para serem enviados por e-mail, não armazenados, como o modelo ContactForm na aplicação base do Yii). No Yii, um modelo baseado em uma tabela do banco de dados é definido como uma classe que estende (ou seja, herda) do Active Record. Active Record é um padrão comum e popular, também usado pelo framework Ruby on Rails. Isto significa que a maior parte da funcionalidade do modelo não está definida no seu modelo, mas sim na classe ActiveRecord pai. Então, quando olhar para o seu código de modelo, não se surpreenda pois você não vai encontrar métodos para a criação e atualização de registros (ou seja, salvar o modelo) dentre outros, isso é tudo herdado. Desde que a funcionalidade já está definida para você, o objetivo do seu modelo deve ser o de ampliar e ajustar essa funcionalidade, conforme necessidade.

Dentro de um modelo, há certos métodos específicos do Yii (funções de classe) que você

normalmente usa. Alguns deles serão criados quando você usar a ferramenta Gii do Yii para gerar o modelo, outros podem sempre ser adicionados. Quero concentrar nos métodos específicos do Yii aqui, como eles serão comuns à maioria dos modelos. (Em capítulos posteriores, vou escrever exemplos de métodos personalizados que podem ser adicionados ao modelo.)

Um dos métodos mais importantes é o rules(), que lista as regras pelas quais os dados do modelo devem obedecer. Grande parte da segurança de sua aplicação e confiabilidade decorre deste método. Na verdade, este método representa um dos principais benefícios do uso de um framework: validação de dados. Se um registro novo está sendo criado ou um já existente é atualizado, você não terá que escrever, replicar e testar as rotinas de validação de dados: o Yii irá fazer isso para você. Como um comentário no modelo indica, você só estabelece regras para os campos (ou seja, atributos do modelo), cujos dados podem ser fornecidos pelos usuários. Você não vai, por exemplo, declarar uma regra para o campo Employee id, que é a chave primária gerada pelo MySQL.

O método rules(), como a maioria dos métodos do Yii, retorna uma matriz de dados:

public function rules(){ return array(/* actual rules */);}

Para as regras efetivamente, a documentação do Yii cobre na íntegra (veja esta e esta), mas vou destacar as principais. Como você vai ver, cada regra é escrita de forma que ela retorna um array.

A primeira, mais óbvia restrição, serve para indicar que um campo é requerido. Basta usar uma string separada por vírgulas com os nomes de campos como o primeiro valor retornado e a palavra required como o segundo:

array('name, email, subject, body', 'required'),

Você também pode especificar que um valor deve ser um número ou, mais especificamente, um número inteiro. Esta sintaxe é um pouco diferente. Aqui, eu indico que o campo ext deve ser um inteiro:

array('ext', 'numerical', 'integerOnly'=>true),

Para strings, você pode restringir o comprimento máximo de um valor:

array('name','length','max'=>40),

Ou um comprimento mínimo:

array('name','length','min'=>6),

Ou ambos:

array('name','length','min'=>6, 'max'=>40),

Outra rotina de validação útil é para verificar se uma string é um endereço de e-mail. Eu faço isso aqui, num campo userEmail:

array('userEmail', 'email'),

Para indicar que uma string deve ser uma URL, use:

array('link', 'url'),

Outra regra útil é a para comparações, como quando um usuário se registra e você tem que ter certeza que a confirmação de senha coincida com a senha:

array('password1', 'compare', 'compareAttribute'=>'password2', 'on'=>'register'),

Há também a regra de "seguro" (safe). Essa regra é usada para fornecer acesso a dados que não são de outra forma validados. Por exemplo, um endereço de e-mail já é considerado "seguro", porque tem de cumprir a regra de e-mail, mas o modelo Employee tem o campo leaveDate que não terá quaisquer regras aplicadas a ele (em parte, porque não há regras de data específicas e também porque o campo pode ser NULL). Para ser capaz de se referir a esse valor, ele deve ser declarado como seguro:

array('leaveDate', 'safe'),

Se há vários campos para torná-los seguros, apenas separe-os com vírgulas.

Há também uma regra para indicar quais campos devem ser seguros para a busca. Por padrão, todos os campos são seguros em uma busca, mas você pode querer mudar esse comportamento, removendo campos da lista:

array('id, departmentId, firstName, lastName, email, ext, hireDate, leaveDate', 'safe', 'on'=>'search'),

Assim, usando essas informações, o método completo rules() para o meu modelo Employee é:

public function rules(){ return array( array('departmentId, firstName, lastName, email, hireDate', 'required'), array('departmentId, ext', 'numerical', 'integerOnly'=>true), array('firstName', 'length', 'max'=>20), array('lastName', 'length', 'max'=>40), array('email', 'length', 'max'=>60), array('email', 'email'), array('leaveDate', 'safe'), array('id, departmentId, firstName, lastName, email, ext, hireDate, leaveDate', 'safe', 'on'=>'search'), );}

Seguindo em frente, outro método chave do modelo é o relations(), que indica a relação entre os modelos. Se o seu banco de dados foi projetado corretamente, este método já estará devidamente preenchido, novamente graças ao Gii. Veja como o método relations() no modelo Employee se parece:

public function relations(){ return array('department' => array(self::BELONGS_TO, 'Department', 'departmentId') );}

Para a relação é dado um nome, aqui department. A relação indica que a coluna departmentId no modelo Employee (por exemplo, o presente) pertence ao modelo Department. Aqui está como isso funciona: Ao carregar as informações de um funcionário, você também pode carregar qualquer de suas relações. Ao fazer isso, as referências a department irão igualar ao modelo Department relativo ao departamento do empregado. Então, se o objeto $model representa o funcionário (Employee) que está sendo visualizado, então $model->department->nome seria o nome do departamento que o empregado está associado.

No Modelo Department, esta relação é definida assim:

public function relations(){ return array('employees' => array(self::HAS_MANY, 'Employee', 'departmentId') );}

Então, se $model representa um departamento (Department) específico que está sendo visualizado, então $model->employees é um array de objetos Employee, cada um dos quais representando um funcionário (Employee) do departamento.

As relações entre os modelos é essencial em sites MVC complexos. Através de relações devidamente definidas, o conteúdo associado pode ser recuperado. Você aprenderá mais sobre isso nos próximos capítulos.

Seguindo em frente, um método mais trivial, mas ainda assim interessante, é o attributeLabels(). Este método retorna uma matriz associativa de campos e os rótulos utilizados para esses campos em formulários, mensagens de erro e assim por diante. O framework Yii faz um grande trabalho de fazer conversões automaticamente, como tornar firstName em First Name e tornar departmentID em apenas Department. Mas você pode querer personalizar ainda estes. Para o modelo Employee, aqui está o meu código:

public function attributeLabels(){ return array( 'id' => 'Employee ID', 'departmentId' => 'Department', 'firstName' => 'First Name', 'lastName' => 'Last Name', 'email' => 'Email', 'ext' => 'Ext', 'hireDate' => 'Hire Date', 'leaveDate' => 'Leave Date', );}

Portanto, há um pouco de personalização que você vai querer fazer em seus modelos para começar. Como eu disse, você também adicionará seus próprios métodos mais tarde. E há algumas outros métodos Yii específicos que uso frequentemente, como beforeSave(), que é o código a ser executado antes de um modelo ser salvo, e beforeValidate(), que é executado antes da validação ocorrer. Este último método é útil se há alguma manipulação de dados que você quer fazer nos bastidores antes do modelo ser processado através de todos os requisitos de validação. E há o método search(), que eu vou ter que endereçar em um capítulo separado. Mas, os métodos mais importantes do Modelo são os rules() e relations().

Edições básicas nas visões no YiiQuando você usa a linha de comando e ferramentas do Gii para criar um novo aplicativo Web, o framework Yii gera uma série de arquivos e pastas para você, de arquivos de configuração até controladores e visões. As visões são uma série de scripts PHP, organizado por pastas. O primeiro que você vai querer editar é protected/views/layouts/main.php (onde protected é o diretório raiz do aplicativo). Este é o template para cada página dentro do aplicativo. É provável que você deseje alterar a maior parte do arquivo para criar o seu próprio visual, mas quero destacar alguns pontos-chave.

Para iniciar no cabeçalho (HEAD), você verá que os arquivos externos são ligados utilizando

<link rel="stylesheet" type="text/css" href="<?php echo Yii::app()->request->baseUrl; ?>/css/main.css" />

Sempre que você vê Yii::app(), que se refere ao aplicativo Web como um todo. Você pode acessar as informações sobre o usuário visualizando uma página, sobre a página atual ou vistas previamente, etc. Yii::app()->request especificamente faz referência a página atual que está sendo

acessada (ou solicitada). A parte ->baseUrl refere-se à URL raiz do aplicativo, como http://www.example.com. Você deve usar Yii::app()->request->baseUrl para referenciar arquivos externos, CSS, JavaScript, imagens, e assim por diante, pois o caminho relativo a eles pode se tornar confuso com as URLs modificadas do Yii (como www.example.com/index.php/site/login).

Em seguida, você verá o título da página configurado dinamicamente:

<title><?php echo CHtml::encode($this->pageTitle); ?></title>

Por padrão, o valor pageTitle será o nome do aplicativo (definido no arquivo de configuração), mais alguma coisa relativa a página atual. Mais tarde, eu vou lhe mostrar como mudar isso. O método CHtml::encode() é usado apenas para proteger contra Cross-Site Scripting (XSS). Você vai vê-lo usado constantemente (e apropriadamente) nos arquivos de visão.

Você também vai ver no arquivo de layout principal:

<div id="logo"><?php echo CHtml::encode(Yii::app()->name); ?></div>

Yii::app()->name é o nome do aplicativo Web, conforme estabelecido no arquivo de configuração config/main.php. Você pode ou não querer usá-lo em suas visões, mas é daí que o valor vem.

Em seguida, o layout padrão usa um widget:

<?php $this->widget('zii.widgets.CMenu',array(...

Widgets são uma maneira de incluir código PHP em uma visão usando um arquivo externo. Eles são melhores para as coisas que não estão ligadas a visões específicas e que você pode querer incluir em qualquer lugar. Além disso, ele permite que você separe código em pedaços para facilitar o gerenciamento e portabilidade. O código acima diz que o widget CMenu deve ser inserido aqui. Ele faz parte da extensão Zii (para o framework Yii). Para saber mais sobre widgets, consulte a documentação do Yii.

Para o Yii 1.1: o Yii 1.1 pegou um monte das melhores extensões e colocou-as em seu próprio namespace, zii. Enquanto em versões anteriores do Yii havia um componente MainMenu, no Yii 1.1 há o widget CMenu. O layout padrão também faz uso do widget CBreadcrumbs, incluído nas extensões do Zii.

Finalmente, o script de layout tem esta linha, que é a mais importante:

<?php echo $content; ?>

Agora você não vai encontrar uma referência para a variável $content em qualquer lugar em seu código e note que é apenas $content, não é $this->content ou $model->content. Esta variável é onde o conteúdo específico da página é inserido no layout. Todo o código HTML e PHP restante define o template para todo o site, o valor de $content é o que faz a páginaX diferente da páginaY. Então, de onde vem isso?

Dica: A estrutura exata das URLs dependerá se você ativou o urlManager ou não e, se sim, como está configurado. Veja o capítulo sobre a configuração do Yii para mais informações.

Se você está vendo uma página como www.example.com/index.php/employee/view/id/1, que se destina a mostrar o empregado com o ID 1, o método actionView() da classe EmployeeController é chamado . Esse método carrega o modelo Employee com a chave primária de 1, então renderiza a visão view, passando o modelo no processo. Esse código é (este é do protected/controllers/EmployeeController.php):

public function actionView($id){ $this->render('view',array( 'model'=>$this->loadModel($id), ));

}

O método loadModel() desta classe Controller faz a recuperação do modelo, e não vou me preocupar com isso agora, mas o código $this->render() diz para renderizar a visão informada, neste caso, view. Isso significa que o Yii irá executar o script PHP protected/views/employee/view.php. Esse script usa uma variável $model (passada no código acima) para exibir informações sobre o funcionário dentro de um contexto (especificamente, o script view.php usa zii.widgets.CDetailView para listar os detalhes). O resultado deste script de visão executado é, nos bastidores, atribuído para $content, e, portanto, colocado no local apropriado do layout. É assim que o sistema funciona.

Uma última coisa sobre os scripts de layout é que você pode facilmente ter layouts diferentes para diferentes seções do aplicativo. Para isso, no método do Controller, altere o valor do layout antes de renderizar a visão. Forneça o nome do arquivo de layout, sem a extensão. Então esta linha diz para usar protected/views/layouts/home.php para a ação index:

class SiteController extends CController{... public function actionIndex() {... $this->layout = 'home';

Na verdade, a partir do Y 1.1.?, o framework cria layouts de uma coluna e duas colunas, cada um dos quais utiliza o arquivo de layout main.php. O controlador então indica qual layout usar para todo o controlador:

class EmployeeController extends Controller{ public $layout='//layouts/column2';

Nota: $this->layout dentro de um método de classe é equivalente a apenas $layout público fora de qualquer método (como no código acima). O primeiro exemplo altera o layout para uma ação específica, o segundo para o controlador como um todo.

Passando para os scripts de visão, uma das primeiras coisas que eu normalmente faço é alterar a formatação básica para o que você está querendo. Por exemplo, a aparência padrão de uma visão view é uma tabela de informações sobre o modelo: rótulos e valores. Normalmente, você não vai querer mostrar todos os dados do modelo, e você vai exibi-los em DIVs ou parágrafos. Estas são alterações simples. Como mostra o código acima, a informação do modelo será passada sob o nome model, de modo que você pode usar $model->whatever para acessar os valores dos diferentes campos.

Para o Yii 1.1: Uma série de alterações nos arquivos de visões foram feitas, embora nenhuma dramática: o que antes era list.php é agora index.php. A página index faz uso de um widget CListView para listar os registros. A página de administração faz uso de um widget CGridView para exibir todos os registros. O arquivo show.php agora é chamado de view.php. Ele faz uso do widget CDetailView para mostrar as informações de um registro específico. Múltiplos arquivos de visão podem fazer uso do script _view.php, que é um modelo para mostrar um registo individual. Cada arquivo de visão identifica informações contidas no breadcrumb na parte superior, que vai associar ao widget CBreadcrumbs referenciado no arquivo de layout principal.

Dica: Se você entrar no site (usando admin/admin, se você não tiver alterado o sistema de login) e depois ir para www.example.com/index.php/department/, você já pode criar alguns registros de departamentos para melhor entendimento do que eu vou escrever abaixo.

As visões index e admin mostram múltiplos registros de modelo, usando widgets do Zii. index.php usa o widget CListView, usando o script _view.php como template. Se você quiser editar o

_view.php ou como o CListView está configurado (no index.php), você vai alterar as listagens. A página admin, acessada clicando em "Manage XXX", usa o widget CGridView. Este elemento cria uma tabela de dados, com links para visualizar, editar ou excluir registros específicos. A tabela pode ser paginada e filtrada, usando Ajax. Esta é uma grande demonstração de quanto o Yii irá fazer por você. Esta figura mostra a lista de departamentos, sem ter feito qualquer alteração no que o Yii criou:

As visões create e update tem algumas coisas de cabeçalho da página, e incluem a visão do formulário, usando este código:

<?php echo $this->renderPartial('_form', array('model'=>$model)); ?>

Esse código renderiza uma visão parcial no local, e repassa a informação de modelo para _form.php.

Olhando para o código gerado, o formulário Department será suficiente, uma vez que apenas fornece uma entrada para o nome do departamento. Para o modelo Employee, no entanto, há alguma personalização que você precisa para fazer. Você pode verificá-la indo para www.example.com/index.php/employee/create/.

Por padrão, os formulários gerados pelo Gii incluem elementos para cada atributo do modelo, exeto para a chave primária. Mas alguns campos, como as datas de criação (created) ou alteração (modified), podem ser automaticamente preenchidos com data e hora, e, portanto, não são inseridos pelos usuários. E, com os modelos relacionados, como Employee e Department, você vai acabar precisando de um menu drop-down num para selecionar um valor a partir do outro, como escolher o departamento que um empregado está dentro. O código gerado pelo Yii não faz isso por você, o formulário só vai ter um campo de texto criado por este código:

<?php echo $form->textField($model,'departmentId'); ?>

A variável $form é um objeto do tipo CActiveForm. O método textField() cria uma entrada de texto. O primeiro argumento diz que a entrada deve ser para o objeto $model (que é a instância do Model atual, que vem do Controller). O segundo argumento identifica a propriedade no modelo para o qual este elemento é.

Para criar um drop-down associado com um outro modelo, você deve substituir o código com:

<?php echo $form->dropDownList($model,'departmentId', CHtml::listData(Department::model()->findAll(), 'id', 'name')); ?>

Primeiro, o método dropDownList() do objeto $form cria uma lista drop-down. Você precisa amarrá-lo ao Model de forma associada, de modo que o primeiro argumento é apenas o $model, a mesma variável passada para a visão quando ela é processada. O segundo argumento é o nome do

campo de formulário/Modelo: aqui, o campo departmentID no modelo Employee. Em seguida, você precisa fornecer ao método a lista de valores para usar no menu drop-down, que é obtido chamando CHtml::listData(). Esse método retorna uma lista de valores que são utilizáveis em menus. Sua fonte de dados deve ser a lista de Departments. Para recuperá-los, use a abordagem do Yii para recuperar todos os registros em um modelo: ModelName::model()->findAll(). Então, para buscar cada departamento, utilize Department::model()->findAll(). Os dois últimos argumentos (para o método CHtml::listData()) são os campos a serem usados para o valor do menu drop-down e texto exibido. Esses devem ser id (o ID do departamento) e name.

Outra coisa que você vai querer fazer em todos os seus arquivos de visão é remover ou editar os links para as diferentes funcionalidades de administração.

Finalmente, você pode decidir que quer mudar o título da página. Para fazer isso, use um código como:

<?php $this->pageTitle = $model->something; ?>

Observe que você está atribuindo um valor para $this->pageTitle aqui, e não para $model->pageTitle, mas provavelmente você vai usar o conteúdo de $model, como um campo de título ou nome, como o valor do título da página. Você também pode ainda adicionar o nome do aplicativo, se você quiser, concatenando com Yii::app()->name.

Ufa! Então, esse é o meu tour relâmpago de edições básicas nas visões que você vai querer fazer uma nova aplicação Yii. No próximo capítulo, vou discutir edições básicas nos controladores, as quais são surpreendentemente poucas, eu acho. Como sempre, obrigado por ler o que tenho a dizer e deixe-me saber se você tiver quaisquer perguntas ou comentários.

Edições básicas nos controladores no YiiPara o Yii 1.1: A linha $defaultAction não está mais presente. Além disso, os nomes de alguns dos métodos de ação (action) foram alterados para coincidir com os novos nomes dos arquivos de visão correspondentes: actionView() e actionIndex().

O Controlador representa as ações que um usuário faz em um site: visualiza um registro específico, atualiza um registro, lista todos os registros, etc. Uma solicitação do usuário (ou seja, o carregamento de uma URL) é tratada pela aplicação Yii, em seguida, passada para o controlador correspondente. É dever do controlador realizar qualquer trabalho necessário, provavelmente envolvendo o carregamento ou a manipulação de alguns modelos, em seguida, passar dados para a visão. Como acontece com qualquer definição de classe, todas as tarefas são realizadas dentro de métodos.

A primeira coisa que você vai encontrar dentro de uma classe Controller é uma variável chamada $layout:

public $layout='//layouts/column2';

Como explicado no capítulo sobre visões, esta variável determina qual dos dois layouts pré-criados (de uma coluna ou duas colunas) o controlador utiliza. Você pode alterar esse valor para alterar o layout de todo o controlador, ou você pode mudar $this->layout dentro de qualquer um dos métodos.

Outra variável de classe, que costumava ser escrita para a classe, mas agora tem de ser adicionada é:

public $defaultAction='admin';

Assim formulado, controladores são as ações que alguém faz, listando informações, mostrando registros específicos, manipulando envios de formulários, e assim por diante. Para cada ação, há um método correspondente na classe controladora: actionIndex(), actionView(), actionCreate(), etc. A

linha acima determina qual é o método chamado, se não especificado explicitamente. Assim, com essa linha, a URL www.example.com/index.php/employee chama o método actionAdmin() enquanto www.example.com/index.php/employee/create chama actionCreate(). O padrão, se você não usar essa linha, é chamar actionIndex().

Seus controladores também devem ter vários métodos não-ação, incluindo accessRules(). Este método é uma parte fundamental da parte de segurança, ditando quem pode fazer o quê. Para as opções do "quê", você tem suas ações: listar, mostrar, criar, atualizar e excluir. Seu "quem" depende da situação, mas para começar há pelo menos usuários logados e não logados, representados por * (qualquer um) e @ (usuários logados). Dependendo do sistema de login adotado, você também pode ter os níveis de usuários, como administradores. Assim, o método accessRules() usa todas essas informações e retorna um array de valores. Os valores também são arrays, indicando permissões (permitir ou negar), ações, e usuários:

public function accessRules(){ return array( array('allow', // allow all users to perform 'index' and 'view' actions 'actions'=>array('index','view'), 'users'=>array('*'), ), 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('*'), ), );}

Essa é a configuração padrão, onde qualquer pessoa pode executar as ações index e view, o que significa que qualquer um pode listar todos os registros ou visualizar registros individuais no modelo associado. A próxima seção permite que qualquer usuário logado realize as ações create e update. Em seguida, apenas os administradores podem realizar as ações admin e delete. Finalmente, a regra geral para negar a todos os usuários é adicionada, para cobrir qualquer situação que não foi explicitamente definida. Esta é apenas uma boa prática de segurança. Note que estas regras só se aplicam a este controlador, cada controlador tem suas próprias regras.

Você vai querer personalizar as regras para cada controlador e situação. Por exemplo, eu fiz um site com um sistema de assinatura, representado por um modelo Contact. Nesse caso, todos tinham permissão para criar registros novos de contato, mas apenas o administrador foi autorizado a listar ou mostrar registros de contato. Geralmente, porém, acho que a maioria dos controladores deve permitir que todos possam realizar as ações view e index.

Você também pode criar condicionais mais sofisticadas para criar permissões, mas isso será assunto para outro momento. Por exemplo, em um projeto que fiz, qualquer usuário conectado poderia criar certos tipos de conteúdo, mas eles só poderiam atualizar e excluir registros que eles próprios criaram. Ou você pode permitir que usuários visualizem apenas o seu próprio registro de contato.

Finalmente, você pode precisar mudar seus controladores, de modo que a recuperação de registros de modelo seja tratada de forma diferente. Existem alguns métodos que carregam registros para serem utilizados em uma visão. Alguns dos métodos, como actionView() e actionUpdate(),

chamam um método loadModel() cujo trabalho é recuperar um único registro. Outros métodos, como actionIndex() e actionAdmin() recuperam todos os registros do modelo (usando uma abordagem diferente). Nestes métodos, há algumas mudanças que você pode querer fazer. Para começar, se o modelo em questão está relacionado a um outro modelo, como definido no método relations() da classe de modelo (veja o capítulo sobre Modelos), você pode invocar essa relação quando você recuperar o registro(s). Por exemplo, este código vai recuperar um funcionário, além do departamento daquele empregado:

$model=Employee::model()->with('department')->findByPk((int)$id);

Você só vai quer fazer isso se você for usar os registros relacionados, é claro.

Você também pode ajustar os critérios (criteria) aplicados a estes métodos, mas esse é um grande tema. Ela envolve basicamente a adição da cláusula WHERE no SQL de uma consulta. Eu vou endereçar isso em outro momento, mas você também pode ver a documentação do Yii, é claro.

Então, isso concluí a série de oito capítulos sobre o framework Yii. Eu tenho um monte de temas diversos sobre o assunto para escrever a respeito, mas eu não vou escrever sobre eles aqui, como parte desta série. Para encontrá-los acesse http://www.larryullman.com/tag/yii/.

Como sempre, obrigado pela leitura e avise-me se você tem algum comentário ou perguntas.

Larry