Dia 1: Iniciando o Projeto

Introdução

O framework symfony tem sido um projeto Open-Source por mais de três anos e tornou-se um dos mais populares frameworks PHP graças as suas poderosas características e a sua excelente documentação. E esta grandiosa tradição iniciou cedo.

Em dezembro de 2005, logo após o primeiro lançamento oficial do symfony, nós publicamos o "tutorial Askeet", um conjunto de 24 tutoriais, publicados dia-a-dia entre o dia primeiro de Dezembro e o Natal.

Este tutorial tem provado ser uma valiosa ferramenta para promover o framework para os recém-chegados. Muitos desenvolvedores aprenderam symfony graças ao askeet, e muitas empresas ainda utilizam o askeet como seu principal material de treinamento.

Nós estamos agora celebrando o lançamento do symfony 1.2 e o tutorial askeet começa a mostrar sua idade. Portanto, é hora de um outro tutorial novo.

Apresentamos Jobeet, o tutorial do calendário de advento 2008!

O Desafio

É isso mesmo, vamos fazê-lo novamente. Todos os dias, incluindo finais de semana, um novo tutorial será publicado. Cada tutorial terá a duração aproximada de uma hora, e será uma ocasião para aprender o symfony codificando um site real, do início ao fim.

Uma hora vezes vinte e quatro é igual a um dia, e esse é exatamente o tempo que pensamos que um desenvolvedor precisa para aprender os fundamentos do symfony. Todos os dias, novos recursos serão adicionados à aplicação, e nós vamos aproveitar esse desenvolvimento para lhe apresentar as novas funcionalidades do symfony, bem como as boas práticas de desenvolvimento web com o symfony.

Para o askeet, o 21º dia foi o "get-a-symfony-guru-for-a-day". Não tínhamos um plano, e a comunidade teve que propor uma funcionalidade para acrescentar ao askeet. Foi um grande sucesso e a comunidade decidiu que precisávamos de um motor de busca para a aplicação. E nós fizemos isso. O tutorial do dia 21 também provou ser um dos mais populares tutoriais do askeet.

Para o Jobeet, nós iremos comemorar o inverno no dia 21º com o "dia do design". Após 4 dias, você vai ter todas as informações HTML e CSS necessárias para iniciar o design do website público para o Jobeet. Portanto, se você trabalha com um designer, ou se sua empresa tem um departamento de design, você poderá contribuir com um design. No dia 21, vamos organizar uma enquete e a comunidade irá escolher o design padrão que será adotado para o Jobeet. Você vai receber, é claro, todos os créditos e a fama associados à ele!

Este Tutorial é diferente

Lembre-se dos primórdios do PHP4. Ah, la Belle Epoque! PHP foi uma das primeiras linguagens dedicadas à web e uma das mais fáceis de aprender.

Mas, como as tecnologias web evoluem em um ritmo muito rápido, os desenvolvedores web precisam manter-se em dia com as mais recentes ferramentas e melhores práticas. A melhor maneira de aprender é, naturalmente, lendo blogs, tutoriais e livros. Nós lemos muitos deles, sejam eles escritos em PHP, Python, Java, Ruby, ou Perl, e muitos deles são insuficientes quando o autor começa dando trechos de códigos como exemplos.

Você provavelmente já encontrou advertências em suas leituras como as seguintes:

"Para uma aplicação real, não esqueça de adicionar validação e manuseio de erro adequado."

ou

"A segurança é deixada como um exercício para o leitor."

ou

"Você irá naturalmente precisar escrever testes."

O quê? Essas coisas são negócio sério. Elas são talvez a parte mais importante de qualquer pedaço de código. E, como um leitor, você é deixado sozinho. Sem essas preocupações levadas em conta, os exemplos são muito menos úteis. Você não pode utilizá-los como um bom ponto de partida. Isso é mau! Por quê? Porque a segurança, a validação, o manuseio de erro e os testes, só para citar alguns, zelam para um código correto.

Neste tutorial, você nunca vai ver declarações como estas, vamos escrever testes, manuseio de erro, código de validação e ter certeza que nós desenvolvemos uma aplicação segura. Isso porque o symfony é sobre código, mas também sobre as melhores práticas e formas de desenvolver aplicações profissionais para a empresa. Podemos nos permitir este luxo porque o symfony fornece todas as ferramentas necessárias para codificar estes aspectos facilmente, sem escrever muito código.

Validação, manuseio de erro, segurança e testes são cidadãos de primeira classe no symfony, assim não será necessário muito tempo para explicar. Esta é apenas uma das muitas razões porque devemos utilizar um framework para projetos da "vida real".

Todo o código que você vai ler neste tutorial é código que você poderá utilizar para um projeto real. Nós encorajamos você a copiar e colar trechos de código ou a roubar todos eles.

O Projeto

A aplicação que será concebida poderia ser ainda um outro mecanismo de blog. Mas nós queremos usar o symfony em um projeto útil. O objetivo é demonstrar que o symfony pode ser utilizado para desenvolver aplicações profissionais e com estilo tendo pouco esforço.

Iremos manter o conteúdo do projeto secreto para outro dia, pois nós já temos muito o que fazer hoje. No entanto, você já sabe o nome da aplicação: Jobeet.

O que para hoje?

Como 24 horas é muito tempo para desenvolver uma aplicação com symfony, não vamos escrever código PHP hoje. Mas, mesmo sem escrever uma única linha de código, você vai iniciar compreendendo as vantagens de utilizar um framework como o symfony, só por inicializar um novo projeto.

O objetivo do dia é a configuração do ambiente de desenvolvimento e exibir uma página da aplicação em um navegador web. Isto inclui a instalação do symfony, a criação de uma aplicação e a configuração do servidor da web.

Pré-requisitos

Antes de mais nada, verifique se você já tem um ambiente de desenvolvimento web com um servidor web (Apache, por exemplo), um mecanismo de banco de dados (MySQL, PostgreSQL, ou SQLite), e PHP 5.2.4 ou posterior.

Como vamos utilizar muito a linha de comando, é melhor usar um sistema operacional Unix-like, mas se você tem um sistema Windows, ele também irá funcionar bem, você só tem que digitar alguns comandos no prompt cmd.

Como o foco deste tutorial será principalmente no framework symfony, vamos assumir que você já tem um sólido conhecimento de PHP 5 e Programação Orientada à Objeto.

Instalação do symfony

Primeiro, crie um diretório para hospedar os arquivos relacionados ao projeto Jobeet:

$ mkdir -p /home/sfprojects/jobeet
$ cd /home/sfprojects/jobeet

No Windows:

c:\> mkdir c:\development\sfprojects\jobeet
c:\> cd c:\development\sfprojects\jobeet

Crie um novo diretório para hospedar os arquivos de biblioteca do framework symfony:

$ mkdir -p lib/vendor

Para instalar o symfony, faça o download do pacote de arquivo encontrado no website do symfony. Como este tutorial foi escrito para o symfony 1.2, faça o download da última versão disponível para esta versão.

Sob a seção "Source Download", você irá encontrar o arquivo no formato .tgz ou .zip. Faça o download do arquivo, coloque ele no diretório recém-criado lib/vendor e descompacte ele:

$ cd lib/vendor
$ tar zxpf symfony-1.2-latest.tgz
$ mv symfony-1.2.0 symfony

No Windows, pode-se utilizar o explorer para descompactar o arquivo zip. Após você renomear o diretório para symfony, deve haver um diretório chamado c:\development\sfprojects\jobeet\lib\vendor\symfony.

Como as configurações PHP variam muito de uma distribuição para outra, nós precisamos verificar se a sua configuração do PHP atende aos requisitos mínimos do symfony. Execute o script verificador de configuração fornecido com o symfony a partir da linha de comando:

$ cd ../..
$ php lib/vendor/symfony/data/bin/check_configuration.php

Se existir um problema, a saída vai te dar dicas sobre como corrigí-lo. Você também deve executar o verificador a partir de um navegador, pois a configuração PHP pode ser diferente. Copie o arquivo em algum lugar sob o diretório raiz do servidor web e acesse o arquivo. Não se esqueça de depois remover o arquivo do diretório raiz da web.

Se o script não apresentar qualquer erro, verifique se o symfony está corretamente instalado usando a linha de comando para exibir a versão (note que a letra V é maiúscula):

$ php lib/vendor/symfony/data/bin/symfony -V

No Windows:

c:\> cd ..\..
c:\> php lib\vendor\symfony\data\bin\symfony -V

Se você está curioso para saber o que esta linha de comando pode fazer por você, digite symfony para listar as opções e tarefas disponíveis:

$ php lib/vendor/symfony/data/bin/symfony

No Windows:

c:\> php lib\vendor\symfony\data\bin\symfony

A linha de comando do symfony é a melhor amiga do desenvolvedor. Ela fornece uma grande quantidade de utilitários que melhoram sua produtividade nas atividades do dia-a-dia, como, limpeza do cache, geração de código e muito mais.

Configuração do Projeto

No symfony, aplicações que compartilham o mesmo modelo de dados são agrupadas em projetos. Para o projeto Jobeet, nós teremos duas aplicações diferentes: uma frontend e uma backend.

Criação do Projeto

No diretório jobeet, execute a tarefa symfony generate:project para realmente criar o projeto symfony:

$ php lib/vendor/symfony/data/bin/symfony generate:project jobeet

No Windows:

c:\> php lib\vendor\symfony\data\bin\symfony generate:project jobeet

A tarefa generate:project gera a estrutura de diretório padrão e os arquivos necessários para o projeto symfony:

A tarefa generate:project também criou um atalho symfony no diretório raiz do projeto Jobeet para diminuir o número de caracteres que você precisa escrever ao executar uma tarefa.

Então, de agora em diante, em vez de utilizar o caminho qualificado completo para o programa symfony, nós iremos usar o atalho symfony.

Criação da aplicação

Agora, crie a aplicação frontend executando a tarefa generate:app:

$ php symfony generate:app --escaping-strategy=on --csrf-secret=Unique$ecret frontend

c:\> copy lib\vendor\symfony\data\bin\symfony.bat .

Mais uma vez, a tarefa generate:app cria a estrutura de diretório padrão necessária para uma aplicação sob o diretório apps/frontend:

Ao chamar a tarefa generate:app, nós também passamos duas opções relacionadas à segurança:

• --escaping-strategy: Habilita output escaping para evitar ataques XSS
• --csrf-secret: Habilita session tokens em formulários para evitar ataques CSRF

Passando estas duas opções para a tarefa, nós temos assegurado o nosso futuro desenvolvimento das duas vulnerabilidades mais difundidas encontradas na web. É isso mesmo, o symfony automaticamente irá tomar as medidas de segurança em nosso favor.

O caminho symfony

Você pode obter a versão do symfony utilizada pelo seu projeto, escrevendo:

$ php symfony -V

A opção -V também exibe o caminho para o diretório de instalação do symfony, que é encontrado em config/ProjectConfiguration.class.php:

// config/ProjectConfiguration.class.php
require_once '/Users/fabien/work/symfony/dev/1.2/lib/autoload/sfCoreAutoload.class.php';

Para uma melhor portabilidade, altere o caminho absoluto da instalação do symfony para um relativo:

// config/ProjectConfiguration.class.php
require_once dirname(__FILE__).'/../lib/vendor/symfony/lib/autoload/sfCoreAutoload.class.php';

Dessa forma, você pode mover o diretório do projeto Jobeet para qualquer lugar da sua máquina ou um outro local, e ele vai funcionar.

Os ambientes

Se você der uma olhada no diretório web/, encontrará dois arquivos PHP: index.php e frontend_dev.php. Esses arquivos são chamados front controllers: todos os pedidos para a aplicação são feitos através deles. Mas porquê nós temos dois front controllers se nós definidos somente uma aplicação?

Ambos os arquivos apontam para a mesma aplicação, mas para diferentes ambientes. Quando você desenvolve uma aplicação, exceto se você desenvolver diretamente no servidor de produção, você precisará de diversos ambientes:

• O ambiente de desenvolvimento: Este é o ambiente usado pelos desenvolvedores web para adicionar novas funcionalidades, corrigir bugs, ...
• O ambiente de teste: este ambiente é usado para automaticamente testar a aplicação.
• O ambiente staging: Este ambiente é usado pelo cliente para testar a aplicação e reportar bugs ou funcionalidades que faltaram.
• O ambiente de produção: Este é o ambiente onde o usuário final interage.

O que torna um ambiente único? No ambiente de desenvolvimento, a aplicação precisa gravar em log todos os detalhes de um pedido para facilitar a depuração, deve exibir exceções no navegador, mas o sistema de cache deve ser desativado e todas as mudanças feitas no código devem ser levadas em conta imediatamente. Então, o ambiente do desenvolvimento deve ser otimizado para o desenvolvedor:

Mas, no ambiente de produção, a aplicação deve exibir mensagens de erro personalizadas ao invés de exceções no estado original, e, naturalmente, a camada de cache deve ser ativada. Então, o ambiente de produção deve ser otimizado para desempenho e experiência do usuário.

Um ambiente symfony é um conjunto exclusivo de definições de configuração e, o symfony, por padrão, já vem com três deles: dev, teste e prod.

Se você abrir os arquivos front controller, você vai ver que a única diferença é a definição do ambiente:

// web/index.php
<?php
 
require_once(dirname(__FILE__).'/../config/ProjectConfiguration.class.php');
 
$configuration = ProjectConfiguration::getApplicationConfiguration('frontend', 'prod', false);
sfContext::createInstance($configuration)->dispatch();

Configuração do Servidor Web: O modo feio

Na seção anterior, foi criado um diretório para hospedar o projeto Jobeet. Se você criou ele em algum lugar sob o diretório web raiz do seu servidor web, você já pode acessar o projeto em um navegador web.

Claro, como não há nenhuma configuração, é muito rápido de definir, mas tente acessar o arquivo config/databases.yml no seu navegador para compreender as más consequências desta atitude de preguiça.

Nunca, jamais utilize esta configuração em um servidor de produção e leia a próxima seção para saber como configurar o seu servidor web corretamente.

Configuração do Servidor Web: O modo seguro

Uma boa prática é colocar sob o diretório web raiz apenas os arquivos que precisam ser acessados por um navegador web como StyleSheets, JavaScripts, ou imagens. E, por padrão, nós recomendamos armazenar esses arquivos sob o sub-diretório web do projeto symfony.

Se você olhar neste diretório, você encontrará alguns sub-diretórios para web assets e os dois arquivos front controllers. Os front controllers são os únicos arquivos PHP que precisam estar sob o diretório raiz web. Todos os outros arquivos PHP podem ficar ocultos para o navegador, o que é uma boa idéia no que se refere a segurança.

Configuração do Servidor Web

Agora, é hora de modificar suas configuraçcões no Apache para tornar o novo projeto acessível para o mundo.

Localize e abra o arquivo de configuração httpd.conf e adicione a seguinte configuração no final:

# Certifique-se que esta linha aparece apenas uma vez em sua configuração
NameVirtualHost 127.0.0.1:8080

# Esta é a configuração para o Jobeet
Listen 127.0.0.1:8080

<VirtualHost 127.0.0.1:8080>
  DocumentRoot "/home/sfprojects/jobeet/web"
  DirectoryIndex index.php
  <Directory "/home/sfprojects/jobeet/web">
    AllowOverride All
    Allow from All
  </Directory>

  Alias /sf /home/sfprojects/jobeet/lib/vendor/symfony/data/web/sf
  <Directory "/home/sfprojects/jobeet/lib/vendor/symfony/data/web/sf">
    AllowOverride All
    Allow from All
  </Directory>
</VirtualHost>

Alias /sf "c:\development\sfprojects\jobeet\lib\vendor\symfony\data\web\sf"

c:\development\sfprojects\jobeet\web

Esta configuração faz com que o Apache "escute" a porta 8080 da sua máquina, então o website Jobeet estará acessível na seguinte URL:

http://localhost:8080/

Você pode alterar 8080 para qualquer número, mas, prefira números maiores que 1024 pois eles não exigem direitos administrativos.

# This is the configuration for Jobeet
<VirtualHost 127.0.0.1:80>
  ServerName jobeet.localhost
  <!-- same configuration as before -->
</VirtualHost>

127.0.0.1         jobeet.localhost

Teste a Nova Configuração

Reinicie o Apache, e verifique se você tem acesso agora à nova aplicação abrindo o seu navegador e digitando http://localhost:8080/index.php/ ou http://jobeet.localhost/index.php/ dependendo da configuração do Apache que você escolheu na seção anterior.

Você também deve tentar acessar a aplicação no ambiente do desenvolvimento. Digite a seguinte URL:

http://jobeet.localhost/frontend_dev.php/

A barra de ferramentas de debug web deverá ser exibida no canto superior direito, incluindo pequenos ícones, provando que sua configuração do alias sf/ está correta.

Subversion

É uma boa prática a utilização de controle de versão ao desenvolver uma aplicação web. Com a utilização de controle de versão é possível:

• trabalhar com confiança
• reverter para uma versão anterior se uma mudança quebrar algo
• permitir que mais de uma pessoa trabalhe eficientemente no projeto
• ter acesso a todas as versões sucessivas da aplicação

Nesta seção, iremos descrever como utilizar o Subversion com symfony. Se você usa outra ferramenta para o controle do código fonte, deverá ser bem fácil adaptar para o que vamos descrever para o Subversion.

Vamos supor que você já tem acesso a um servidor Subversion.

Primeiro, crie um novo repositório para o projeto jobeet:

$ svnadmin create http://svn.example.com/jobeet
$ svn mkdir -m "created default directory structure" http://svn.example.com/jobeet/trunk http://svn.example.com/jobeet/tags http://svn.example.com/jobeet/branches

Então, remova o conteúdo dos diretórios cache/ e log/ pois não queremos colocá-los no repositório.

$ cd /home/sfprojects/jobeet
$ rm -rf cache/*
$ rm -rf log/*

Agora, certifique-se de definir as permissões nos diretórios cache e log para os níveis adequados, para que o seu servidor web possa escrever neles:

$ chmod 777 cache
$ chmod 777 log

Em seguida, faça a primeira importação:

$ svn import -m "made the initial import" . http://svn.example.com/jobeet/trunk

Como nunca iremos fazer commit dos arquivos localizados nos diretórios cache/ e /log, você precisará especificar uma lista de ignorados:

$ svn propedit svn:ignore cache

O editor de texto padrão configurado para o SVN deverá ser executado. O Subversion deve ignorar todo o conteúdo deste diretório:

*

Salvar e sair. Está pronto.

Repita o procedimento para o diretório log/:

$ svn propedit svn:ignore log

E informe:

*

Finalmente, faça o commit destas alterações no repositório:

$ svn commit -m "added cache/ and log/ content in the ignore list"

  $ svn co http://svn.jobeet.org/tags/release_day_01/ jobeet/

Vejo você amanhã

Bem, o tempo acabou por hoje! Mesmo que ainda não começamos a falar sobre o symfony, temos uma configuração sólida do ambiente de desenvolvimento, falamos sobre as melhores práticas em desenvolvimento web, e estamos prontos para iniciar a codificação.

Amanhã, vamos revelar o que a aplicação irá fazer e iniciar o mergulho no symfony. Neste meio tempo, se quiser manter o contato com as notícias mais recentes do Jobeet, não esqueça de assinar o feed no blog do symfony.

Certifique-se de voltar amanhã!