Development

sfBookPT-brFilestructexp

You must first sign up to be able to contribute.

Version 12 (modified by hpoyatos, 11 years ago)
--

Estrutura de arquivos explicada

Resumo

A estrutura em árvore de um projeto symfony é consistente, embora possa ser completamente customizada. Este capítulo o ajudará a fazer uso desta estrutura e entender a lógica por detrás dela.

Introdução

Todos os projetos web generalmente compartilhando as mesmas necessidades de arquitetura:

  • banco de dados
  • arquivos estáticos (HTML, imagens, javascripts, folhas de estilo (CSS), etc.)
  • arquivos enviados para o site através de usuários e administradores
  • classes e bibliotecas PHP
  • bibliotecas de terceiros
  • arquivos de carga (batch)
  • arquivos de log
  • arquivos de configurações
  • etc.

Para permitir desenvolvedores se adaptarem a qualquer projeto symfony existente, recomendamos seguir a estrutura em árvore padrão descrita abaixo. Isso também acelera o processo de criação do projeto, uma vez que a estrutura é automaticamente criada quando inicializamos qualquer projeto, aplicação ou módulo.

Estrutura em árvore raiz

Estes são os diretórios encontrados na raiz do projeto Symfony:

apps/
  fo/
  bo/
batch/
cache/
config/
data/
  sql/
doc/
  api/
lib/
  model/
log/
test/
web/
  css/
  images/
  js/
  uploads/

O diretório de carga (batch) é usado por arquivos php chamados a partir da linha de comandos ou agendados para rodar em processos de carga.

O cache do projeto, usado para acelerar a resposta das requisições web, está localizado no diretório cache. Cada aplicação terá seu subdiretório lá dentro, contendo HTML pré-processadas e arquivos de configuração.

A configuração geral do projeto está armazenada no diretório de configuração (config).

No diretório data, você pode armazenar arquivos de dados do projeto, como o esquema de um banco de dados, arquivos SQL que criem tabelas, ou até mesmo um banco de dados SQLite se você precisar.

No diretório doc fica armazenada a documentação do projeto, incluindo seus próprios arquivos de documentação gerados pelo phpdoc (no subdiretório api).

O diretório lib é dedicado às classes de terceiros e bibliotecas. Aqui você pode o código que precise ser compartilhado por outras aplicações. O subdiretório model armazena os modelos de objeto do projeto.

O diretório log armazena arquivos de log gerados diretamente pelo symfony. Pode conter também logs do servidor web, logs de bancos de dados ou logs de qualquer parte do projeto. Normalmente é um arquivo por aplicação e por ambiente. (ex: myapp_prod.log)

O diretório test contém unidades de testes escritos em PHP e compatíveis com o framework de testes Simple Test. Durante o setup do projeto, Symfony automaticamente insere alguns stubs com alguns testes básicos.

O diretório web é a raiz do seu servidor web. Os únicos arquivos acessíveis da Internet são os localizados neste diretório. Ele será descrito em detalhes em alguns instantes.

Por último e não menos importante, o diretório apps contém um diretório para cada aplicação do projeto (tipicamente fo e bo para o front e back office, myapp em um exemplo).

Estrutura em árvore da aplicação

A estrutura em árvore para todos os diretórios de aplicação é a mesma:

config/
i18n/
lib/
modules/
templates/
  layout.php
  error.php
  error.txt

O diretório config contém um conjunto robusto de arquivos de configuração YAML. E aí onde se concentra boa parte da configuração da aplicação, excetuando-se apenas dos parâmetros padrão encontrados no próprio framework. Note que os parâmetros padrão ainda podem ser sobreescritos aqui se isso for necessário. Você pode encontrar mais informações sobre configurações de aplicação no capítulo relacionado.

O diretório i18n contém arquivos usados para a internacionalização de uma aplicação. Estes arquivos podem ser em formato XLIFF ou GetText. Você pode inclusive desprezar esse diretório se escolher usar um banco de dados para sua internacionalização.

O diretório lib contém classes e bibliotecas que são específicas para a aplicação.

O diretório modules armazena todos os módulos que contém as funcionalidades da aplicação.

O diretório templates lista os templates globais da aplicação, aqueles que serão compartilhados por todos os módulos. Por padrão, contém um arquivo layout.php, que é o layout principal para cada template de módulo inserido; um error.php, usado para saída de erros de requisições web; e um error.txt usado para saídas de erro quando a aplicação é chamada sem um navegador web (no caso de unidades de testes, por exemplo). Outro template global pode ser inserido aqui - se sua aplicação usa pop-ups compartilhando um mesmo layout, você pode inserir um popuplayout.php, por exemplo.

Os diretórios i18n, lib e modules estarão vazios em uma nova aplicação.

O nome do diretório de uma aplicação é determinado durante seu setup. Este nome é acessível via o objeto sfConfig referenciando sfConfig::get('sf_app_dir').

As classes de uma aplicação não estão habilitadas a acessar métodos ou atributos de outras aplicações de um mesmo projeto. Note também que links entre duas aplicações de um mesmo projeto devem utilizar caminho absoluto.

Estrutura em árvore do Módulo

Cada aplicação contém um ou mais módulos. Cada módulo possui seu próprio subdiretório no diretório modules, e o nome deste diretório é escolhido durante seu setup.

Esta é uma típica estrutura em árvore de um módulo:

actions/
  actions.class.php
config/
lib/
templates/
  indexSuccess.php
validate/

O diretório actions geralmente contém um única classe chamada actions.class.php, onde você pode armazenar todas as ações de um módulo. Ações diferentes de um módulo também podem ser escritos em arquivos separados.

O diretório config pode conter configurações customizadas com parâmetros locais de um módulo.

O diretório lib contém classes e bibliotecas específicas para o módulo.

O diretório templates contém os templates correspondentes para as ações do módulo. Um template padrão é criado durante o setup do módulo, chamado de indexSuccess.php.

E o diretório validate é dedicado a arquivos de configurações usados para validações de formulários.

Os diretórios config, lib e validate estarão vazios em uma nova aplicação.

Estrutura em árvore Web

Estes muito poucas restrições para um diretório web, mas se forem seguidas algumas conveções básicas elas resultarão em comportamentos padrão e atalhos úteis nos templates.

Por convenção, os arquivos estáticos são distribuídos nos seguintes diretórios:

  • css/: folhas de estilos (CSS) em extensão .css
  • js/ : javascripts com a extensão .js
  • images/ : imagens com formatos/extensões .jpg, .png ou .gif

Os arquivos resultados de uploads por usuários devem ser armazenados no diretório uploads. Mesmo que, na grande maioria das vezes, diretórios de uploads contenham imagens, devem ser distintos do diretório de imagens para com que a sincronização de ambientes de desenvolvimento e produção não afetem as imagens enviadas.

Customização da estrutura em árvore

Ainda que seja altamente recomendável manter a estrutura em árvore padrão, é possível modificá-la para necessidades específicas, por exemplo orientado-a para coincidir com requisitos de um cliente que já possui sua própria estrutura em árvore e convenções de codificação.

Cada caminho para um diretório chave é determinado por um parâmetro terminado em "_dir". Estes parâmetros são definidos no framework, em um arquivo chamado $pear_data_dir/symfony/config/constants.php, usado por todo projeto symfony. Para customizar a estrutura em árvore de uma aplicação, você precisa simplesmente sobrescrever estes valores dos parâmetros. Para isso, use o arquivo config.php localizado em apps/myapp/config/ (para estrutura de diretórios de aplicação), ou config/config.php (para estruturas de projeto).

Você provavelmente terá que copiar a configuração padrão do diretório do symfony se precisar modificá-la. Eis aqui a reprodução da configuração padrão:

// escrutura de diretórios raiz
'sf_cache_dir_name'   => 'cache',
'sf_log_dir_name'     => 'log',
'sf_lib_dir_name'     => 'lib',
'sf_model_dir_name'   => 'model',
'sf_web_dir_name'     => 'web',
'sf_data_dir_name'    => 'data',
'sf_config_dir_name'  => 'config',
'sf_apps_dir_name'    => 'apps',
 
// estrutura de diretórios global
'sf_app_dir'        => $sf_root_dir.DIRECTORY_SEPARATOR.'apps'.DIRECTORY_SEPARATOR.$sf_app,
'sf_model_dir'      => $sf_root_dir.DIRECTORY_SEPARATOR.'model',
'sf_lib_dir'        => $sf_root_dir.DIRECTORY_SEPARATOR.'lib',
'sf_web_dir'        => $sf_root_dir.DIRECTORY_SEPARATOR.'web',
'sf_upload_dir'     => $sf_root_dir.DIRECTORY_SEPARATOR.'web'.DIRECTORY_SEPARATOR.'uploads',
'sf_base_cache_dir' => $sf_root_dir.DIRECTORY_SEPARATOR.'cache'.DIRECTORY_SEPARATOR.$sf_app,
'sf_cache_dir'      => $sf_root_dir.DIRECTORY_SEPARATOR.'cache'.DIRECTORY_SEPARATOR.$sf_app.DIRECTORY_SEPARATOR.$sf_environment,
'sf_log_dir'        => $sf_root_dir.DIRECTORY_SEPARATOR.'log',
'sf_data_dir'       => $sf_root_dir.DIRECTORY_SEPARATOR.'data',
'sf_config_dir'     => $sf_root_dir.DIRECTORY_SEPARATOR.'config',

Nomes e caminhos são ambos definidos aqui. Apesar do arquivo não ser muito fácil de ler, é muito fácil de modificar.

Importante: É altamente recomendado usar estes parâmetros (via objeto sfConfig) ao invés de seus valores quando estiver construindo e codificando um projeto. Desta forma, as aplicações criadas tornam-se independentes de estruturas de diretórios, mais particularmente para o primeiro nível de diretórios.

     [php]
     // always prefer
     if(file_exists(sfConfig::get('sf_log_dir').'myLogFile.log'))
     // instead of
     if(file_exists('/home/myproject/log/myLogFile.log'))

Por exemplo, se você quiser que sua escrutura de arquivos parece com esta (esta é um estrutura de host compartilhado padrão):

cgi-bin/
  apps/
    fo/
    bo/
  batch/
  cache/
  config/
  data/
    sql/
  doc/
    api/
  lib/
    model/
  log/
  test/
public_html/
  css/
  images/
  js/
  uploads/
  index.php

Modifique a constante SF_ROOT_DIR definida em index.php (e de outros controladores frontais) de:

define('SF_ROOT_DIR', realpath(dirname(__FILE__).'/..'));

para

define('SF_ROOT_DIR', realpath(dirname(__FILE__).'/../../cgi-bin'));

Então adicione as linhas abaixo no seu config/config.php:

$sf_root_dir = sfConfig::get('sf_root_dir');   
sfConfig::add(array(
  'sf_web_dir_name' => $sf_web_dir_name    = 'public_html',
  'sf_web_dir'      => $sf_root_dir.DIRECTORY_SEPARATOR.'..'.DIRECTORY_SEPARATOR.$sf_web_dir_name,
  'sf_upload_dir'   => $sf_root_dir.DIRECTORY_SEPARATOR.'..'.DIRECTORY_SEPARATOR.$sf_web_dir_name.DIRECTORY_SEPARATOR.$sf_upload_dir_name,       
));