Development

Documentation/fr_FR/book/trunk/file_structure

You must first sign up to be able to contribute.

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.

Arborescence d'un module

Chaque application contient un ou plusieurs modules. Chaque module a son propre sous-dossier dans le dossier modules, et le nom de ce dossier est choisi lors de la création du module.

Voici l'arborescence typique d'un module :

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

Le dossier actions contient en général une unique classe nommée actions.class.php, dans laquelle vous pouvez placer toutes les actions du module. Des actions différentes d'un même module peuvent également être écrites dans des fichiers séparés.

Le dossier config peut contenir des fichiers de configuration personnalisés avec des paramètres locaux au module.

Le dossier lib contient des classes et des librairies spécifiques au module.

Le dossier templates contient les templates correspondant aux actions du module. Un template par défaut est créé au cours de la création du module, il est appelé indexSuccess.php.

Enfin, le dossier validate est dédié aux fichiers de configuration utilisés pour la validation des formulaires.

Les dossiers config, lib et validate sont vides pour chaque nouveau module.

Arborescence Web

Il y a très peu de contraintes sur le dossier web, mais le respect de quelques conventions de nommage permet d'utiliser certains comportements et raccourcis utiles dans les templates.

Par convention, les fichiers statiques sont répartis dans les dossiers suivants :

  • css/: feuilles de styles avec une extension .css
  • js/: javascripts avec une extension .js
  • images/: images au format .jpg, .png ou .gif

Les fichiers uploadés par les utilisateurs doivent être enregistrés dans le dossier uploads. Même si, la plupart du temps, ce dossier uploads contient des images, il est distinct du dossier des images, de telle sorte que la synchronisation des environnements de production et de développement n'a aucune conséquence sur les images uploadées.

Paramétrage de l'arborescence

Même s'il est fortement recommandé de conserver l'arborescence par défaut, il est possible de la modifier pour répondre à des besoins spécifiques, par exemple afin de s'adapter aux exigences d'un client habitué à une arborescence et des conventions de codage données.

Chaque chemin vers un dossier clé est détermimé par un paramètre se terminant par le suffixe _dir. Ces paramètres sont définis dans le framework, dans un fichier nommé $pear_data_dir/symfony/config/constants.php, et utilisé par chaque projet Symfony. Afin de personnaliser l'arboresence de l'application, vous devez simplement surcharger ces réglages en utilisant le fichier config.php situé dans le dossier apps/myapp/config/ (pour une structure de dossiers spécifique à une application), ou le fichier config/config.php (pour un paramétrage à l'échelle du projet).

Vous voudrez sans doute copier la configuration depuis le dossier de Symfony, si vous souhaitez la modifier. Voici un extrait de cette configuration par défaut :

// 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',

Les noms et les chemins sont définis ici. Même si ce fichier n'est pas de lecture aisée, il est facile à modifier.

Important : Il est fortement recommandé d'employer ces paramètres (accessibles via l'objet sfConfig) au lieu de leurs valeurs lorsque vous développez un projet. De cette manière, les applications créées sont indépendantes de l'arborescence, en particulier pour le premier niveau de dossiers.

     [php]
     // préférez toujours
     if(file_exists(sfConfig::get('sf_log_dir').'myLogFile.log'))
     // plutôt que
     if(file_exists('/home/myproject/log/myLogFile.log'))

Par exemple, si vous souhaitez que votre arborescence ressemble à ceci (il s'agit d'une arborescente standard pour un hébergement mutualisé) :

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

Changez la constante SF_ROOT_DIR, définie dans le index.php (et les autres contrôleurs) en remplaçant :

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

par

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

Puis ajoutez les lignes suivantes à votre 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,       
));