Development

Documentation/fr_FR/book/trunk/file_structure

You must first sign up to be able to contribute.

Version 5 (modified by xavier, 11 years ago)
continuing translation

Cette partie de la documentation est en cours de traduction. Cela signifie qu'elle est traduite de manière soit incomplète, soit inexacte. En attendant que cette traduction soit terminée, vous pouvez consulter la version en anglais pour des informations plus fiables. Vous pouvez également participer à la traduction de cette page en vous inscrivant sur la page d'avancement des traductions.

L'arborescence de Symfony

Résumé

L'arbrescence d'un projet Symfony est structurée, même si elle peut entièrement être adaptée. Ce chapitre a pour objectif de vous habituer à cette structure et à en comprendre la logique.

Introduction

En général, tous les projets Web partagent les mêmes besoins d'architecture :

  • base de données
  • fichiers statiques (HTML, images, javascripts, feuilles de styles, etc.)
  • téléchargement sur le serveur de fichiers par les utilisateurs ou les administrateurs du site
  • classes et librairies PHP
  • librairies externes
  • fichiers de commande (fichiers batch)
  • fichiers de journal (logs)
  • fichiers de configuration
  • etc.

Afin que les développeurs puissent s'adapter à tout projet Symfony existant, il est conseillé de se conformer à l'arborescence par défaut, décrite ci-dessous. Ceci permet notamment d'accélérer la création de projets, cette arborescence par défaut étant créée automatiquement à l'initialisation d'un projet, d'une application ou d'un module.

Structure de fichiers racine

Voici les dossiers que l'on peut trouver à la racine d'un projet Symfony :

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

Le dossier batch est destiné aux fichiers PHP appelés en ligne de commande ou par une planificateur de taches afin d'effectuer des traitements par lot.

Le cache du projet, employé pour répondre plus rapidement aux requêtes Web, est situé dans le dossier cache. Chaque application dispose d'un sous-dossier contenant des fichiers HTML prêts à être servis, et des fichiers de configuration préalablement traités.

La configuration générale du projet est enregistrée dans le dossier config.

Dans le dossier data, vous pouvez stocker les fichiers de donnée du projet, comme un schéma de base de données, un fichier SQL pour la création des tables, ou encore une base de données SQLite si vous en avez besoin.

Le dossier doc contient la documentation du projet, ce qui inclut vos propres documents et la documentation générée par phpdoc (dans le sous-dossier api).

Le dossier lib est destiné à des classes externes ou à des librairies. Vous pouvez y ajouter du code qui doit être partagé entre plusieurs applications. Le sous-dossier model contient le modèle objet du projet.

Le dossier log contient les fichiers de log applicatifs, directement générés par Symfony. Ce dossier peut également contenir les fichiers de log du serveur, les fichiers de log de la base de données ou les fichiers de log d'une quelconque partie du projet. Il y a normalement un fichier de log par application et par environnement (ex: myapp_prod.log)

Le dossier test contient les tests unitaires, écrits en PHP et compatibles avec le cadre de tests SimpleTest. Au cours de l'initialisation du projet, Symfony y ajoute automatiquement du code avec quelques tests basiques.

Le dossier web est la racine pour le serveur Web. Les fichiers situés dans ce dossier sont les seuls accessibles depuis Internet. Ce dossier sera décrit plus en détail dans quelques instants.

Enfin, le dossier apps contients un sous-dossier pour chaque application du projet (typiquement, fo et bo pour le front-office et le back-office, myapp dans l'exemple donné ci-dessus).

Arborescence d'une application

Tous les dossiers d'applications ont la même structure :

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

Le dossier config contient un ensemble complet de fichiers de configuration YAML. C'est à cet endroit que se fait la plus grosse partie de la configuration de l'application, en dehors des paramètres par défaut qui se trouvent dans le framework lui-même et peuvent être surchargés dans le dossier config si nécessaire. Vous trouverez plus d'explications au sujet de la configuration d'une application dans le chapitre suivant (voir cette page sur la documentation anglaise).

Le dossier i18n contient les fichiers nécessaires à l'internationalisation de l'application. Ces fichiers peuvent être écrits aux formats XLIFF ou GetText. Vous pouvez vous passer de l'emploi de ce dossier si vous choisissez d'utiliser une base de données pour l'internationalisation de votre projet.

Le dossier lib contient les classes et les librairies qui sont propres à l'application.

Dans le dossier modules se trouvent les modules qui proposent les fonctionnalités de l'application.

Le dossier templates liste les templates de l'application, c'est-à-dire ceux qui sont partagés entre tous les modules. Par défaut, on y trouve un fichier layout.php, qui est le layout au sein duquel les templates des modules sont insérés; un fichier error.php, employé pour afficher les erreurs suite à une requête Web; et un fichier error.txt utilisé pour afficher les erreurs lorsque l'application n'est pas appelée par un navigateur Web (par exemple, lors de tests unitaires). C'est dans ce dossier qu'il faut ajouter d'autres éventuels templates globaux - si votre application emploie des popups ayant le même layout, vous pouvez par exemple créer un fichier a popuplayout.php.

Les dossiers i18n, lib et modules sont vides pour toute nouvelle application.

Le nom du dossier d'une application est déterminé au cours de sa création. Ce nom est accessible par le biais de l'objet sfConfig, en appelant sfConfig::get('sf_app_dir').

Les classes d'une application ne peuvent pas accéder aux méthodes ou aux attributs d'autres applications du même projet. Notez également que les liens hypertexte entre deux applications d'un même projet doivent être écrits sous forme absolue.

Module tree structure

Each application contains one or more modules. Each module has its own subdirectory in the modules directory, and the name of this directory is chosen during the setup.

This is the typical tree structure of a module:

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

The actions directory generally contains a single class named actions.class.php, in which you can store all the actions of the module. Different actions of a module can also be written in separate files.

The config directory can contain custom configuration files with local parameters for the module.

The lib directory contains classes and libraries specific to the module.

The templates directory contains the templates corresponding to the actions of the module. A default template is created during module setup, called indexSuccess.php.

And the validate directory is dedicated to configuration files used for form validation.

The directories config, lib and validate are empty for a new module.

Web tree structure

There are very few constraints for the web directory, but following a few basic naming conventions will provide default behaviors and useful shortcuts in the templates.

Conventionally, the static files are distributed in the following directories:

  • css/: stylesheets with a .css extension
  • js/: javascripts with a .js extension
  • images/: images with a .jpg, .png or .gif format

The files uploaded by the users have to be stored in the uploads directory. Even though, most of the time, the uploads directory contains images, it is distinct from the image directory so that the synchronization of the development and production environments does not affect the uploaded images.

Tree structure customization

Even if it is highly recommended to keep the default tree structure, it is possible to modify it for specific needs, for instance in order to match the requirements of a client who already has its own tree structure and coding conventions.

Every path to a key directory is determined by a parameter ending with _dir. These parameters are defined in the framework, in a file called $pear_data_dir/symfony/config/constants.php, used by every symfony project. To customize the tree structure of an application, you simply need to override these settings. For that, use the config.php file located in the apps/myapp/config/ directory (for an application-wide directory structure), or the config/config.php (for a project-wide structure).

You will probably have to copy the default configuration from the symfony directory if you need to modify it. Here is an extract of the default configuration:

// root directory structure
'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',
 
// global directory structure
'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',

Names and paths are both defined here. While this file is not that easy to read, it is easy to modify.

Important: It is strongly recommended to use these parameters (via the sfConfig object) instead of their values when building and coding a project. That way, the applications created can be independent of the tree structure, more particularly for the first level directories.

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

For instance, if you want your file structure to look like this (it is a standard shared host structure):

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

Change the SF_ROOT_DIR constant defined in the index.php (and the other front controllers) from:

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

to

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

Then add the following lines to your 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,       
));