Documentação do Symfony
Renderizada do repositório symfony-docs-pt-BR no Github

Criando o projeto

Instalando o Symfony

Há apenas uma maneira recomendada para instalar o Symfony:

Composer é o gerenciador de dependência usado por aplicações PHP modernas. Adicionar ou remover requisitos para o seu projeto e atualizar as bibliotecas de terceiros usadas em seu código é muito fácil graças ao Composer.

Gerenciamento de Dependência com o Composer

Antes de instalar o Symfony, você precisa certificar-se de que tem o Composer instalado globalmente. Abra o seu terminal (também chamado de console de comando) e execute o seguinte comando:

$ composer --version
Composer version 1e27ff5e22df81e3cd0cd36e5fdd4a3c5a031f4a 2014-08-11 15:46:48

Você provavelmente verá um identificador de versão diferente. Não se preocupe porque o Composer é atualizado em uma base contínua e sua versão específica não importa.

Instalando o Composer Globalmente

No caso de você não ter o Composer instalado globalmente, execute os dois comandos seguintes se você usa Linux ou Mac OS X (o segundo comando irá pedir a sua senha de usuário):

$ curl -sS https://getcomposer.org/installer | php
$ sudo mv composer.phar /usr/local/bin/composer

Note

Dependendo da sua distribuição Linux, você pode precisar executar o comando su em vez de sudo.

Se você usa um sistema Windows, baixe o instalador executável da página de download do Composer e siga os passos para instalá-lo.

Criando a Aplicação Blog

Agora que tudo está configurado corretamente, você pode criar um novo projeto usando o Symfony. Em seu console de comando, navegue até o diretório onde você tem permissão para criar arquivos e execute os seguintes comandos:

$ cd projects/
$ composer create-project symfony/framework-standard-edition blog/

Esse comando irá criar um novo diretório chamado blog que conterá um novo projeto usando a versão estável mais recente disponível do Symfony.

Verificando a Instalação do Symfony

Uma vez que a instalação estiver concluída, entre no diretório blog/ e verifique se o Symfony está instalado corretamente, executando o seguinte comando:

$ cd blog/
$ php app/console --version

Symfony version 2.6.* - app/dev/debug

Se você ver a versão do Symfony instalado, tudo funcionou como esperado. Se não, você pode executar o script a seguir para verificar o que impede o seu sistema de executar as aplicações Symfony corretamente:

$ php app/check.php

Dependendo do seu sistema, você pode ver até duas listas diferentes ao executar o script check.php. A primeira mostra os requisitos obrigatórios que o seu sistema deve atender para executar aplicações Symfony. A segunda lista mostra o requisitos opcionais sugeridos para uma ótima execução das aplicações Symfony:

Symfony2 Requirements Checker
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

> PHP is using the following php.ini file:
  /usr/local/zend/etc/php.ini

> Checking Symfony requirements:
  .....E.........................W.....

[ERROR]
Your system is not ready to run Symfony2 projects

Fix the following mandatory requirements
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 * date.timezone setting must be set
   > Set the "date.timezone" setting in php.ini* (like Europe/Paris).

Optional recommendations to improve your setup
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 * short_open_tag should be disabled in php.ini
   > Set short_open_tag to off in php.ini*.

Tip

Os lançamentos do Symfony são assinados digitalmente por razões de segurança. Se você quiser verificar a integridade da instalação do Symfony, dê uma olhada no repositório público de checksums e siga esses passos para verificar as assinaturas.

Estruturando a Aplicação

Depois de criar a aplicação, entre no diretório blog/ e você verá arquivos e diretórios que foram gerados automaticamente:

blog/
├─ app/
│  ├─ console
│  ├─ cache/
│  ├─ config/
│  ├─ logs/
│  └─ Resources/
├─ src/
│  └─ AppBundle/
├─ vendor/
└─ web/

Essa hierarquia de arquivos e diretórios é a convenção proposta pelo Symfony para estruturar suas aplicações. O objetivo recomendado de cada diretório é o seguinte:

  • app/cache/, armazena todos os arquivos de cache gerados pela aplicação;
  • app/config/, armazena todas as configurações definidas para qualquer ambiente;
  • app/logs/, armazena todos os arquivos de log gerados pela aplicação;
  • app/Resources/, armazena todos os templates e os arquivos de tradução da aplicação.
  • src/AppBundle/, armazena o código específico do Symfony (controladores e rotas), seu código de domínio (por exemplo, classes do Doctrine) e toda a sua lógica de negócio;
  • vendor/, esse é o diretório onde o Composer instala as dependências da aplicação e você nunca deve modificar quaisquer dos seus conteúdos;
  • web/, armazena todos os arquivos de front controller e todos os assets web, tais como folhas de estilo, arquivos JavaScript e imagens.

Bundles da aplicação

Quando o Symfony 2.0 foi lançado, a maioria dos desenvolvedores naturalmente adotou a forma de dividir as aplicações em módulos lógicos do Symfony 1.x. É por isso que muitas apps Symfony usam bundles para dividir seu código em recursos lógicos: UserBundle, ProductBundle, InvoiceBundle, etc.

Mas um bundle é designado para ser algo que possa ser reutilizado como um pedaço de software stand-alone. Se UserBundle não pode ser usado “como é” em outras apps Symfony , então não deve ter seu próprio bundle. Além disso, InvoiceBundle depende do ProductBundle, então, não há nenhuma vantagem em ter dois bundles separados.

A implementação de um único bundle AppBundle em seus projetos vai tornar o seu código mais conciso e fácil de entender. A partir do Symfony 2.6, a documentação oficial do Symfony usa o nome AppBundle.

Note

Não há necessidade de prefixar o AppBundle com seu próprio vendor (por exemplo, AcmeAppBundle), pois este bundle de aplicação nunca será compartilhado.

Ao todo, esta é a estrutura de diretórios típica de uma aplicação Symfony que segue as melhores práticas:

blog/
├─ app/
│  ├─ console
│  ├─ cache/
│  ├─ config/
│  ├─ logs/
│  └─ Resources/
├─ src/
│  └─ AppBundle/
├─ vendor/
└─ web/
   ├─ app.php
   └─ app_dev.php

Tip

Se você estiver usando o Symfony 2.6 ou uma versão mais recente, o bundle AppBundle já foi gerado para você. Se você estiver usando uma versão mais antiga do Symfony, você pode gerá-lo, executando o seguinte comando manualmente:

$ php app/console generate:bundle --namespace=AppBundle --dir=src --format=annotation --no-interaction

Estendendo a Estrutura de Diretório

Se o seu projeto ou a infraestrutura requer algumas alterações na estrutura de diretórios padrão do Symfony, você pode sobrescrever a localização dos diretórios principais: cache/, logs/ e web/.

Além disso, o Symfony3 usará uma estrutura de diretório ligeiramente diferente quando ele for lançado:

blog-symfony3/
├─ app/
│  ├─ config/
│  └─ Resources/
├─ bin/
│  └─ console
├─ src/
├─ var/
│  ├─ cache/
│  └─ logs/
├─ vendor/
└─ web/

As mudanças são bastante superficiais, mas, por hora, nós recomendamos que você use a estrutura de diretórios do Symfony2.