Development

Documentation/fr_FR/book/1.0/trunk/05-Configuring-Symfony

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.

Traducteur : Nicocsgamer, début trad : 20/07/2007, fin prévue : 20/08/2007

Chapitre 5 – Configurer Symfony

Pour etre simple et facile à utiliser, symfony a définit quelques conventions, ce qui devrait répondre aux égigences de la plupart des applications standards sans besoin de modification .Cependant, en utilisant un ensemble de fichiers de configuration simples et puissants, il est possible de presque tout modifier la façon dont le framework et votre application intéragit les uns avec les autres. Avec ces fichiers, vous pourrez également ajouter des paramètres spécifiques à vos applications.

Ce chapitre explique comment fonctionne le système de configuration :

  • La configuration de symfony est stockée dans des fichiers écris en YAML, cependant vous pouvez choisir d'autres formats.
  • Les fichiers de configuration se trouvent au niveau du projet, de l'application, et des modules dans la hiérarchie du projet.
  • Vous pouvez définir un ensemble de configuration; dans symfony, un ensemble de configuration est appelé un environnement.
  • Les valeurs définies dans les fichiers de configuration sont accessibles depuis le code PHP de votre application.
  • De plus, symfony autorise du code PHP dans les fichiers YAML, ainsi que d'autres astuces pour rendre le système de configuration bien plus flexible.

Le système de configuration

Regardless of purpose, most web applications share a common set of characteristics. For instance, some sections can be restricted to a subset of users, or the pages can be decorated by a layout, or a form can be filled with the user input after a failed validation. A framework defines a structure for emulating these characteristics, and the developer can further tweak them by changing a configuration setting. This strategy saves a lot of development time, since many changes don't require a single line of code, even if there is a lot of code behind. It is also much more efficient, because it ensures such information can be maintained in a single and easily identifiable location.

Cependant cette approche à deux inconvénients majeurs : * Les développeurs n’en finissent plus d’écrire des fichiers XML. * Dans l’architecture PHP, chaque requête prend plus de temps à s’exécuter.

Prenant ces inconvénient en compte, symfony utilise les fichiers de configurations seulement ce pourquoi ils sont les meilleurs. En fait, l’ambition du système de configuration de symfony est d’être :

  • Puissant : Presque tous les aspects pouvant être gérés par les fichiers de configurations le sont.
  • Simple : Beaucoup d’aspect de configuration ne sont pas affichés dans une application normale, puisque ils ont rarement besoin d’être changé.
  • Facile : Les fichiers de configuration sont faciles lire, à modifier, et à créer par le développeur.
  • Personnalisable: Le langage de configuration par défaut est YAML, mais peut être INI, XML, ou n’importe quel langage que le développeur préfère.
  • Rapide : Les fichiers de configurations ne sont jamais interprétés par l’application mais par le système de configuration, qui les compile en morceaux rapide d’exécution de code pour le serveur PHP.

Syntaxe YAML et les conventions de symfony

Pour sa configuration, symfony utilise le format YAML par défaut, à la place des traditionnels INI ou XML.

Listing 5-1 - YAML Files Forbid Tabs

# Never use tabs
all:
-> mail:
-> -> webmaster:  webmaster@example.com

# Use blanks instead
all:
  mail:
    webmaster: webmaster@example.com

Si vos paramètres de type chaine de caractère commencent ou finissent par des espaces, entourez la valeur de simple quotes. De plus s’ils contiennent des caractères spéciaux, entourez les également la valeur entre simple quotes, comme dans le listing 5-2.

Listing 5-2 – Les chaines de caractères non standards devraient être entourées de simple quotes

error1: Ce champ est obligatoire
error2: '  Ce champ est obligatoire  '
error3: 'Don''t leave this field blank'   # Les simples quotes doivent être doublées

Vous pouvez définir de longues chaines de caractères sur plusieurs lignes, ainsi que des chaines à lignes multiples, grâce aux entêtes spéciales pour chaines de caractères (> et |) suivie d’une indentation. Le listing 5-3 expose cette convention.

Listing 5-3 – Définir des chaines de caractères longues et multi lignes.

# Folded style, introduced by >
# Each line break is folded to a space
# Makes YAML more readable
accomplishment: >
  Mark set a major league
  home run record in 1998.

# Literal style, introduced by |
# All line breaks count
# Indentation doesn't appear in the resulting string
stats: |
  65 Home Runs
  0.278 Batting Average

Pour définir une valeur en tant que tableau, entourez les éléments de crochets ou utilisez la syntaxe étendue avec des tirets, comme montré dans le listing 5-4.

Listing 5-4 – Syntaxe YAML pour les tableaux

# Syntaxe courte pour les tableaux
players: [ Mark McGwire, Sammy Sosa, Ken Griffey ]

# Syntaxe étendue pour les tableaux
players:
  - Mark McGwire
  - Sammy Sosa
  - Ken Griffey

Pour définir une valeur en tant que tableau associatif, ou hash, entourez les éléments d’accolades et insérez toujours un espace entre la clé et la valeur key: value. Vous pouvez également utiliser la syntaxe étendue en ajoutant une indentation et un retour chariot pour chaque nouvelle clé, comme montré dans le listing 5-5.

Listing 5-5 – Syntaxe YAML pour les tableaux associatifs

# Syntaxe incorrecte, il manque un espace après la colonne
mail: {webmaster:webmaster@example.com,contact:contact@example.com}

# Syntaxe courte correcte pour les tableaux associatifs
mail: { webmaster: webmaster@example.com, contact: contact@example.com }

# Syntaxe étendues pour les tableaux associatifs
mail:
  webmaster: webmaster@example.com
  contact:   contact@example.com

Pour donner une valeur Boolean, utilisez on, 1, ou true pour une valeur positive et off, 0, ou false pour une négative. Le listing 5-6 montre les valeurs Boolean possible.

Listing 5-6 – Syntaxe YAML pour les valeurs Boolean possible

true_values:   [ on, 1, true ]
false_values:  [ off, 0, false ]

N’hésitez pas à ajouter des commentaries(commencant par le marqueur ‘#’) et des espaces supplémentaires aux valeurs pour que vos fichiers YAML soient plus lisibles, comme montré dans le listing 5-7.

Listing 5-7 – Syntaxe YAML pour les commentaires et l’alignement des valeurs

# This is a comment line
mail:
  webmaster: webmaster@example.com
  contact:   contact@example.com
  admin:     admin@example.com   # extra spaces allow nice alignment of values

Dans certains fichier de configuration symfony, vous verrez des fois des lignes commençant par un marqueur hash(et ignorés par le parseur YAML) mais ressemblant à l’arrangement habituel des lignes. C’est une convention symfony : la configuration par défaut, héritée des autres fichiers YAML situés dans le noyau symfony, est répétée par des lignes commentées dans la configuration de votre application, pour votre information. Si vous souhaitez changer la valeur d’un tel paramètre, vous devez d’abord décommentez la ligne, comme montré dans le listing 5-8.

Listing 5-8 – La configuration par défaut est commentée

# The cache is off by default
settings:
# cache: off

# If you want to change this setting, uncomment the line first
settings:
  cache: on

Symfony regroupe parfois la définition des paramètres en catégories. Tous les paramètres d’une catégorie apparaissent indentés dans l’entête de celle-ci. Structurer de longues listes de paires key: value, en les groupant en catégories augmentent la lisibilité de la configuration. Les entêtes des catégories commencent avec un point (.). Le listing 5-9 montre un exemple de catégorie.

Listing 5-9 – Les entêtes de catégorie ressemblent aux clés, mais commencent par un point.

all:
  .general:
    tax:        19.6

  mail:
    webmaster:  webmaster@example.com

Dans cet exemple, mail est une clé et general n’est que l’entête d’une catégorie. Tout fonctionne comme si l’entête de la catégorie n’existait pas, comme montré dans le listing 5-10. Le paramètre tax est un fils direct de la clé all.

Listing 5-10 – Les entêtes des catégories sont seulement là pour la lisibilité, et sont en faite ignorées.

all:
  tax:          19.6

  mail:
    webmaster:  webmaster@example.com

SIDEBAR Et si vous n’aimez pas YAML

YAML est juste une interface pour définir des paramètres utilisés par PHP, puisque la configuration définie dans les fichiers YAML sera finalement transformée en PHP. Après avoir parcouru une application, vérifiez la configuration de son cache (dans cache/myapp/dev/config/, par exemple). Vous verrez les fichiers PHP correspondants à votre configuration YAML. Vous en apprendrez plus à propos du cache de la configuration plus tard dans ce chapitre.

La bonne nouvelle est ce que si vous ne souhaitez pas utiliser les fichiers YAML, vous pouvez toujours faire vos fichiers de configuration à la main, en PHP ou via un autre format (XML, INI, …). Tout au long de ce livre, vous rencontrerez des alternatives pour définir la configuration sans YAML, et vous apprendrez même à remplacer le gestionnaire de configuration symfony (au chapitre 19). Si vous les utilisez raisonnablement, ces astuces vous permettront de vous passez des fichiers de configuration ou de définir vos propres format de configuration.

A l’aide, un fichier YAML a tué My App!

Les fichiers YAML sont chargés dans des tableaux php, et ensuite les valeurs sont utilisées dans différentes parties de l’application pour modifier le comportement de la vue, du contrôleur, ou du modèle. Beaucoup de fois, quand il y a un problème dans un fichier YAML, il n’est pas détecter tant que la valeur n’est pas utilisée. D’ailleurs, l’erreur ou l’exception qui est levée n’est pas clairement liée au fichier de configuration YAML.

Si votre application s’arrête soudainement de fonctionner après un changement de configuration, vous devriez vérifiez si vous n’avez pas fait une erreur de codeur YAML inattentif :

  • Vous avez oublié un espace entre une clé et sa valeur :

    key1:value1      # Un espace est manquant après le :
    
  • Les clés ne sont pas indentées de la même manière:

    all:
      key1:  value1
       key2: value2  # l’indentation n’est pas la même que les autre membres
      key3:  value3
    
  • Il y a un caractère YAML réservé dans une clé ou une valeur, sans délimiteurs de chaine de caractères:

    message: tell him: go way    # :, [, ], { et } sont réservés pour YAML
    message: 'tell him: go way'  # Syntaxe correcte
    
  • Vous avez modifié une ligne commentée :

    # key: value     # Ne sera jamais prit en compte à cause du #
    
  • Vous avez mit des valeurs avec la meme clé au meme niveau :

    key1: value1
    key2: value2
    key1: value3     # key1 est définie deux fois, la valeur est la dernière modifiée
    
  • Vous pensez que le paramètre est d’un type spécial, alors que c’est toujours une chaine de caractères, tant que vous ne l’avez pas convertit:

    income: 12,345   # Tant que vous ne l’avez pas convertit ca reste une chaine de caractères
    

Vue d’ensemble des fichiers de configuration

La configuration est repartie dans des fichiers, par sujet. Les fichiers contiennent des définitions de paramètre, ou des paramètres. Certains de ces paramètres peuvent surchargés à différents niveaux (projet, application, et module) ; certains sont spécifiques à un certain niveau. Les prochains chapitres traiteront des fichiers de configuration en fonction de leur nature, et le chapitre 19 traitera de la configuration avancée.

Configuration du projet

Il y a quelques fichiers de configuration pour le projet par défaut. Voici la liste des fichiers que l’on peut trouver dans le répertoire myproject/config/ :

  • config.php: C’est le tout premier fichier exécuté par une requête ou une commande. Il contient le chemin des fichiers du framework, et vous pouvez le changer pour utiliser une installation différente. Si vous ajoutez quelques define à la fin de ce fichier, les constantes seront accessibles par toutes les applications du projet. Regardez le chapitre 19 pour les usages avancés de ce fichier.
  • databases.yml: C’est ici que vous définissez l’accès et les paramètres de connexion à la base de données (serveur, login, password, nom de la base, …). Le chapitre 8 vous en dira plus. Ils peuvent être modifiés au niveau application.
  • properties.ini: Ce fichier stocke quelques paramètres utilisés par l’outil en ligne de commande, incluant le nom du projet et des paramètres de connexions pour les serveurs distants. Regardez le chapitre 16 pour un aperçu des fonctionnalités utilisant ce fichier.
  • rsync_exclude.txt: Ce fichier spécifie les répertoires devant êtres exclus des synchronisations entre serveurs. On en parle chapitre 16.
  • schema.yml et propel.ini: Ce sont les fichiers de configurations d’accès aux données utilisés par Propel (la couche ORM de symfony). Ils sont utilisés pour faire fonctionner les librairies Propel avec les classes symfony et les données de votre projet. schema.yml contient une représentation du modèle de données relationnel du projet. propel.ini est automatiquement généré, donc vous n’avez probablement pas besoin de le modifier. Si vous n’utilisez pas Propel, ces fichiers ne sont pas nécessaires. Le chapitre 8 vous en dira plus à propos de leur utilisation.

Ces fichiers sont essentiellement utilisés par des composants externes ou par l’outil en ligne de commande. Ils doivent également êtres traités avant qu’un parser YAML soit chargé par le framework. C’est pourquoi certains d’entre eux n’utilisent pas le format YAML.

Configuration de l’application

La majeure partie de la configuration est celle de l’application. Elle est définie dans le front controller (dans le répertoire web/) pour les constantes principales, dans les fichiers YAML situé dans le répertoire config/ de l’application, dans le répertoire i18n/ pour les fichiers d’internationalisation, et dans les fichiers du framework pour la configuration additionnelle.

Configuration du front controller

La tout première configuration de l’application est situé dans le front controller ; c’est le tout premier script exécuté par une requête. Jetez un œil au fichier par défaut web/index.php dans le listing 5-11.

Listing 5-11 – Le front controller de production par défaut

[php]
<?php

define('SF_ROOT_DIR',    realpath(dirname(__FILE__).'/..'));
define('SF_APP',         'myapp');
define('SF_ENVIRONMENT', 'prod');
define('SF_DEBUG',       false);

require_once(SF_ROOT_DIR.DIRECTORY_SEPARATOR.'apps'.DIRECTORY_SEPARATOR.SF_APP.DIRECTORY_SEPARATOR.'config'.DIRECTORY_SEPARATOR.'config.php');

sfContext::getInstance()->getController()->dispatch();

Après avoir définit le nom de l’application (myapp) et l’environnement (prod), le fichier de configuration général est appelé avec l’envoi. Quelques constantes utiles sont définies ici :

  • SF_ROOT_DIR: répertoire racine du projet (normalement, devrait rester à sa valeur par défaut, à moins que vous ne changiez la structure de fichiers).
  • SF_APP: Nom de l’application dans le projet. Nécéssaire pour définir les chemins de fichiers.
  • SF_ENVIRONMENT: Nom de l’environnement (prod, dev, ou n’importe quelle autre environnement spécifique à un projet que vous avez définit). Déterminera quels paramètres de configuration seront utilisés. Les environnements seront expliqués plus tard dans ce chapitre.
  • SF_DEBUG: Activation du mode debug (regardez le chapitre 16 pour plus de détails).

Si vous souhaitez changer une de ces valeurs, vous aurez probablement d’un front controller supplémentaire. Le chapitre suivant vous en dira plus à propos du front controller et comment en créer un nouveau.

SIDEBAR Le répertoire racine peu être n’importe où

Seulement les fichiers et les scripts situés dans le répertoire racine web (web/ dans un projet symfony) sont accessibles de l’extérieur. Les scripts du front controller, images, feuilles de styles, et les fichiers JavaScript sont publiques. Tous les autres fichiers doivent être à l’extérieur de la racine web du serveur -- cela signifie qu’ils peuvent être n’importe où ailleurs.

Le front controller accède aux fichiers non publics du projet grâce au chemin SF_ROOT_DIR. Classiquement, le répertoire racine est un niveau au dessus du répertoire web/. Mais vous pouvez choisir une structure complètement différente. Imaginez que votre répertoire principal est fait de deux répertoires, un public et l’autre privé :

symfony/    # Private area
  apps/
  batch/
  cache/
  ...
www/        # Public area
  images/
  css/
  js/
  index.php

Dans ce cas, le répertoire racine est le répertoire symfony/. Donc le fichier index.php du front controller a seulement besoin de définir la constante SF_ROOT_DIR de l’application comme ceci pour quelle fonctionne:

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

Le chapitre 19 vous donnera plus d’informations à propos de la modification de symfony pour le faire fonctionner avec une structure de fichiers spécifiques.

Configuration de l'application principale

La configuration de l'application principale est stockée dans des fichiers situés dans le répertoire myproject/apps/myapp/config/:

  • app.yml: Ce fichier devrait contenir la configuration spécifique à l'application;c'est-à-dire les variables globales définissant la logique applicative spécifique à une application, n’ayant pas besoin d’être stockées dans une base de données. Taux des taxes, frais de ports, et e-mail sont souvent stockés dans ce fichier. Il est vide par défaut.
  • config.php: Ce fichier amorce l’application, ce qui veut dire qu’il réalise les initialisations permettant à l’application de démarrer. C’est ici que vous pouvez personnaliser votre structure de fichiers ou ajouter des constantes spécifiques à l’application (le chapitre 19 fournit plus de détails). Il démarre en incluant le fichier config.php du projet.
  • factories.yml: Symfony définit ses propres classes pour gérer la vue, les requêtes, les réponse, les sessions, … . Si vous souhaitez utiliser vos propres classes, c’est ici que vous pouvez les définir. Le chapitre 17 fournit plus d’informations.
  • filters.yml: Les filtres sont des portions de code exécutés à chaque requête. C’est ici que vous définissez quels filtres sont traités, et ils peuvent êtres modifiés pour chaque module. Le chapitre 6 en parle plus précisément.
  • logging.yml: Ce fichier définit le niveau de détails devant être enregistré dans les logs, pour vous aider à gérer et à debugger votre application. L’utilisation de cette configuration est expliquée au chapitre 16.
  • routing.yml: Les règles de routage, permettant de transformer les urls illisibles et « unbookmarkable » en de belles urls, sont stockées dans ce fichier. Pour de nouvelles applications, quelques règles par défaut existent. Le chapitre 9 est consacré aux liens et au routage.
  • settings.yml: Les paramètres principaux d’une application symfony sont stockés dans ce fichier. C’est ici que vous définissez si votre application est à vocation internationale, son langage par défaut, le timeout d’une requête, et si le cache est actif. En changeant une seule ligne dans ce fichier, vous pouvez interrompre l’application vous permettant la maintenance ou la mise à jour d’un de ses composants. Les paramètres communs et leurs utilisations sont décrits dans le chapitre 19.
  • view.yml: La structure de la vue par défaut (nom du layout, titre, et tags meta; feuilles de styles par défaut et les fichiers JavaScript à inclure ; content-type par défaut, …) est définit dans ce fichier. Le chapitre 7 en vous en dire à propos de ce fichier. Ces paramètres peuvent êtres modifiés pour chaque module.

Configuration de l’internationalisation

Les applications internationalisées peuvent afficher des pages dans différentes langues. Ceci requière une configuration spécifique. Il y a deux endroits pour la configuration de l’internationalisation :

  • Le fichier i18n.yml du répertoire config/ : Ce fichier définit les paramètres généraux de traduction, comme la culture par défaut pour les traductions, si les traductions viennent de fichiers ou d’une base de données, et leurs formats.
  • Les fichiers de traduction dans le répertoire i18n/ de l’application : Ce sont des dictionnaires basiques, donnant une traduction pour chaque phrases utilisées dans le template de l’application de sorte que les pages affichent le texte traduit lorsque l’utilisateur change de langue.

Notez que l’activation de la fonctionnalité i18n est réalisée dans le fichier settings.yml. Vous trouverez plus d’informations à propos de cette fonctionnalité dans le chapitre 13.

Configuration supplémentaire pour l’application

Un seconde ensemble de fichiers de configuration se trouve dans le répertoire d’installation de symfony (dans $sf_symfony_ data_dir/config/) et n’apparaît pas dans le répertoire de configuration de votre application. Les paramètres définis ici sont rarement modifiés, ou global à tous les projets. Cependant, si vous avez besoin de les modifier, créer un fichier vide portant le même nom dans le répertoire myproject/apps/myapp/config/, et modifiez les paramètres que vous souhaitez changer. Les paramètres définis dans une application sont toujours prioritaires sur ceux définis dans le framework. Les fichiers de configurations sivants sont ceux du répertoire d’installation de symfony /config :

  • autoload.yml: Ce fichier contient les paramètres de la fonctionnalité d’auto chargement. This feature exempts you from requiring custom classes in your code if they are located in specific directories. Il est décrit en details dans le chapitre 19.
  • constants.php: Ce fichier contient la structure de fichier par défaut de l’application. Pour modifier les parametres de ce fichier, utilisez le fichier config.php de l’application, comme expliqué dans le chapitre 19.
  • core_compile.yml et bootstrap_compile.yml: C’est la liste des classes à inclure lors du démarrage de l’application (dans bootstrap_compile.yml) et pour traiter une requête (dans core_compile.yml). Ces classes sont en fait concaténées dans un fichier PHP optimisé sans commentaires, ce qui va accélérer l’exécution en minimisant les opérations d’accès au fichier (un seul fichier est chargé au lieu d’une quarantaine à chaque requête). Les techniques d’optimisations sont décrites au chapitre 18.
  • config_handlers.yml: C’est ici que vous pouvez ajouter ou modifier les gestionnaires utilisés pour traiter chaque fichier de configuration. Le chapitre 19 fournit plus de details.
  • php.yml: Ce fichier vérifie sur les variables du fichier php.ini sont correctement définies et vous permet de les modifier, si nécessaire. Regardez le chapitre 19 pour plus de détails.

Configuration d’un module

Par défaut, un module n’a pas de configuration spécifique. Mais, si besoin, vous pouvez modifier quelques paramètres du niveau application. Par exemple, vous pourriez faire ceci pour changer la description HTML des actions d’un module, ou pour inclure un fichier JavaScript particulier. Vous pouvez également choisir d’ajouter un paramètre restreint à un module spécifique pour préserver l’encapsulation.

Comme vous pouriez vous en douter, les fichiers de configuration d’un module son situés dans le repertoire myproject/apps/myapp/modules/mymodule/config/. Ces fichiers sont les suivants :

  • generator.yml: Pour les modules générés à partir de la table d’une base de données (scaffoldings and administrations), ce fichier définit comment l’interface affiche les lignes et les champs, et quelles interactions sont proposées à l’utilisateur (filtres, ordonnancement, boutons, …). Le chapitre 14 vous en dira plus sur ça.
  • module.yml: Ce fichier contient des paramètres personnalisés spécifique à un module (équivalent à app. yml, mais au niveau d’un module) et aux action. Le chapitre 6 fournit plus détails.
  • security.yml: Ce fichier définit la restriction d’acces aux actions. C’est ici que vous spécifiez qu’une page peut être vue seulement par les utilisateurs enregistrés ou par un sous-ensemble d’utilisateur enregistrés avec des droits spéciaux. Le chapitre 6 vous en dira plus.
  • view.yml: Ce fichier contient la configuration pour les vues pour une ou toutes les actions du module. Il modifie le fichier view.yml de l’application, comme décrit dans le chapitre 7.
  • Data validation files: Bien que situé dans le répertoire validate/ au lieu de config/, les fichiers YAML de validation de données, utilisés pour contrôler les données entrées dans les formulaire, sont également des fichier de configuration du module. Vous en apprendrez plus sur comment les utiliser au chapitre 10.

La plupart des fichiers de configuration d’un module permettent de définir les paramètres pour toutes les vues ou toutes les actions d’un module, ou pour un sous-ensemble de celui-ci.

SIDEBAR Trop de fichiers?

Vous pourriez être accablé pour le nombre de fichiers de configuration présents dans l’application. Mais s’il vous plait gardez ceci ç l’esprit :

La plupart du temps, vous n’avez pas besoin de modifier la configuration, puisque les conversions par défauts correspondent à la plupart des exigences. Chaque fichier de configuration est relatif à une fonctionnalité particulière, et les prochains chapitres détailleront leur utilisation un par un. Quand vous vous concentrez sur un seul fichier, vous pouvez voir clairement ce qu’il fait et comment il est organisé.

Pour les développements web professionnels, la configuration par défaut n’est pas souvent complètement adaptée. Les fichiers de configuration permettent des modifications faciles des mécanismes de symfony sans code. Imaginez la quantité de code PHP nécessaire pour réaliser la même quantité de contrôle. Si toutes les configurations été dans un seul fichier, non seulement le fichier serait complètement illisible, mais vous ne pourriez pas redéfinir la configuration à différents niveaux (regardez la section précédent «Configuration en cascade » de ce chapitre) > >Le système de configuration est une des forces de symfony, parce qu’il permet à symfony d’être utilisable pour presque tous les types d’application web, et pas seulement pour ceux pour lesquels le framework a été conçu.

Les environnements

Pendant le développement d'une application, vous voudrez sans doute conserver plusieurs ensembles de configuration en parallèle. Par exemple, pendant le développement vous avez une configuration pour une base de donnée de test et une autre pour votre vraie base de donnée en production. Symfony offre la possibilité d'avoir plusieurs configurations concurrentes nommées environnements.

Qu'es qu'un environnement

Une application peut fonctionner dans plusieurs environnements. Les différents environnements partagent le même code PHP (Mis a par le controleur FRONT), mais peuvent avoir une configuration totalement différente. Pour chaque application, symfony fournis trois environnements par défaut: Production (prod), test (test) et développement (dev). Vous êtes libre d'ajouter autant d'environnement que vous le souhaiter.

Les environnement et les configuration sont donc synonyme. Par exemple, l'environnement test enregistrera les alertes et les erreurs alors que l'environnement prod enregistrera uniquement les erreurs. L'accélération du cache est souvent désactivée dans l'environnement dev, mais est activé dans les environnements test et prod. Les environnements test et prod auront besoin d'une base de donnée de test distincte de celle utilisée dans l'environnement de production. La base de donnée sera donc différente entre les deux environnement. Tout les environnements peuvent fonctionner sur la même machine. Bien que le serveur de production ne contient généralement que l'environnement prod.

In the dev environment, the logging and debugging settings are all enabled, since maintenance is more important than performance. On the contrary, the prod environment has settings optimized for performance by default, so the production configuration turns off many features. A good rule of thumb is to navigate in the development environment until you are satisfied with the feature you are working on, and then switch to the production environment to check its speed.

The test environment differs from the dev and prod environment in other ways. You interact with this environment solely through the command line for the purpose of functional testing and batch scripting. Consequently, the test environment is close to the production one, but it is not accessed through a web browser. It simulates the use of cookies and other HTTP specific components.

To change the environment in which you're browsing your application, just change the front controller. Until now, you have seen only the development environment, since the URLs used in the example called the development front controller:

http://localhost/myapp_dev.php/mymodule/index

However, if you want to see how the application reacts in production, call the production front controller instead:

http://localhost/index.php/mymodule/index

If your web server has mod_rewrite enabled, you can even use the custom symfony rewriting rules, written in web/.htaccess. They define the production front controller as the default execution script and allow for URLs like this:

http://localhost/mymodule/index

SIDEBAR Environments and servers

Don't mix up the notions of environment and server. In symfony, different environments are different configurations, and correspond to a front controller (the script that executes the request). Different servers correspond to different domain names in the URL.

http://localhost/myapp_dev.php/mymodule/index
       _________ _____________
        server    environment

Usually, developers work on applications in a development server, disconnected from the Internet and where all the server and PHP configuration can be changed at will. When the time comes for releasing the application to production, the application files are transferred to the production server and made accessible to the end users.

This means that many environments are available on each server. For instance, you can run in the production environment even on your development server. However, most of the time, only the production environment should be accessible in the production server, to avoid public visibility of server configuration and security risks.

To add a new environment, you don't need to create a directory or to use the symfony CLI. Simply create a new front controller and change the environment name definition in it. This environment inherits all the default configuration plus the settings that are common to all environments. The next chapter will show you how to do this.

Configuration Cascade

The same setting can be defined more than once, in different places. For instance, you may want to set the mime-type of your pages to text/html for all of the application, except for the pages of an rss module, which will need a text/xml mime-type. Symfony gives you the ability to write the first setting in myapp/config/view.yml and the second in myapp/modules/rss/config/view.yml. The configuration system knows that a setting defined at the module level must override a setting defined at the application level.

In fact, there are several configuration levels in symfony:

  • Granularity levels:
    • The default configuration located in the framework
    • The global configuration for the whole project (in myproject/config/)
    • The local configuration for an application of the project (in myproject/apps/myapp/config/)
    • The local configuration restricted to a module (in myproject/apps/myapp/modules/mymodule/config/)
  • Environment levels:
    • Specific to one environment
    • For all environments

Of all the properties that can be customized, many are environment-dependent. Consequently, many YAML configuration files are divided by environment, plus a tail section for all environments. The result is that typical symfony configuration looks like Listing 5-12.

Listing 5-12 - The Structure of Symfony Configuration Files

# Production environment settings
prod:
  ...

# Development environment settings
dev:
  ...

# Test environment settings
test:
  ...

# Custom environment settings
myenv:
  ...

# Settings for all environments
all:
  ...

In addition, the framework itself defines default values in files that are not located in the project tree structure, but in the $sf_symfony_data_dir/config/ directory of your symfony installation. The default configuration is set in these files as shown in Listing 5-13. These settings are inherited by all applications.

Listing 5-13 - The Default Configuration, in $sf_symfony_data_dir/config/settings.yml

 # Default settings:
 default:
   default_module:         default
   default_action:         index
   ...

These default definitions are repeated in the project, application, and module configuration files as comments, as shown in Listing 5-14, so that you know that some parameters are defined by default and that they can be modified.

Listing 5-14 - The Default Configuration, Repeated for Information, in myapp/config/settings.yml

#all:
 #  default_module:         default
 #  default_action:         index
 ...

This means that a property can be defined several times, and the actual value results from a definition cascade. A parameter definition in a named environment has precedence over the same parameter definition for all environments, which has precedence over a definition in the default configuration. A parameter definition at the module level has precedence over the same parameter definition at the application level, which has precedence over a definition at the project level. This can be wrapped up in the following priority list:

  1. Module
  2. Application
  3. Project
  4. Specific environment
  5. All environments
  6. Default

The Configuration Cache

Parsing YAML and dealing with the configuration cascade at runtime represent a significant overhead for each request. Symfony has a built-in configuration cache mechanism designed to speed up requests.

The configuration files, whatever their format, are processed by some special classes, called handlers, that transform them into fast-processing PHP code. In the development environment, the handlers check the configuration for changes at each request, to promote interactivity. They parse the recently modified files so that you can see a change in a YAML file immediately. But in the production environment, the processing occurs once during the first request, and then the processed PHP code is stored in the cache for subsequent requests. The performance is guaranteed, since every request in production will just execute some well-optimized PHP code.

For instance, if the app.yml file contains this:

all:                   # Setting for all environments
  mail:
    webmaster:         webmaster@example.com

then the file config_app.yml.php, located in the cache/ folder of your project, will contain this:

[php]
<?php

sfConfig::add(array(
  'app_mail_webmaster' => 'webmaster@example.com',
));

As a consequence, most of the time, the YAML files aren't even parsed by the framework, which relies on the configuration cache instead. However, in the development environment, symfony will systematically compare the dates of modification of the YAML files and the cached files, and reprocess only the ones that have changed since the previous request.

This presents a major advantage over many PHP frameworks, where configuration files are compiled at every request, even in production. Unlike Java, PHP doesn't share an execution context between requests. For other PHP frameworks, keeping the flexibility of XML configuration files requires a major performance hit to process all the configuration at every request. This is not the case in symfony. Thanks to the cache system, the overhead caused by configuration is very low.

There is an important consequence of this mechanism. If you change the configuration in the production environment, you need to force the reparsing of all the configuration files for your modification to be taken into account. For that, you just need to clear the cache, either by deleting the content of the cache/ directory or, more easily, by calling the clear-cache symfony task:

> symfony clear-cache

Accessing the Configuration from Code

All the configuration files are eventually transformed into PHP, and many of the settings they contain are automatically used by the framework, without further intervention. However, you sometimes need to access some of the settings defined in the configuration files from your code (in actions, templates, custom classes, and so on). The settings defined in settings.yml, app.yml, module.yml, logging.yml, and i18n.yml are available through a special class called sfConfig.

The sfConfig Class

You can access settings from within the application code through the sfConfig class. It is a registry for configuration parameters, with a simple getter class method, accessible from every part of the code:

[php]
// Retrieve a setting
parameter = sfConfig::get('param_name', $default_value);

Note that you can also define, or override, a setting from within PHP code:

[php]
// Define a setting
sfConfig::set('param_name', $value);

The parameter name is the concatenation of several elements, separated by underscores, in this order:

  • A prefix related to the configuration file name (sf_ for settings.yml, app_ for app.yml, mod_ for module.yml, sf_i18n_ for i18n.yml, and sf_logging_ for logging.yml)
  • The parent keys (if defined), in lowercase
  • The name of the key, in lowercase

The environment is not included, since your PHP code will have access only to the values defined for the environment in which it's executed.

For instance, if you need to access the values defined in the app.yml file shown in Listing 5-15, you will need the code shown in Listing 5-16.

Listing 5-15 - Sample app.yml Configuration

all:
  version:        1.5
  .general:
    tax:          19.6
  default_user:
    name:         John Doe
  mail:
    webmaster:    webmaster@example.com
    contact:      contact@example.com
dev:
  mail:
    webmaster:    dummy@example.com
    contact:      dummy@example.com

Listing 5-16 - Accessing Configuration Settings in PHP in the dev Environment

[php]
echo sfConfig::get('app_version');
 => '1.5'
echo sfConfig::get('app_tax');   // Remember that category headers are ignored
 => '19.6'
echo sfConfig::get('app_default_user_name');
 => 'John Doe'
echo sfConfig::get('app_mail_webmaster');
 => 'dummy@example.com'
echo sfConfig::get('app_mail_contact');
 => 'dummy@example.com'

So symfony configuration settings have all the advantages of PHP constants, but without the disadvantages, since the value can be changed.

On that account, the settings.yml file, where you can set the framework settings for an application, is the equivalent to a list of sfConfig::set() calls. Listing 5-17 is interpreted as shown in Listing 5-18.

Listing 5-17 - Extract of settings.yml

all:
  .settings:
    available:              on
    path_info_array:        SERVER
    path_info_key:          PATH_INFO
    url_format:             PATH

Listing 5-18 - What Symfony Does When Parsing settings.yml

[php]
sfConfig::add(array(
  'sf_available' => true,
  'sf_path_info_array' => 'SERVER',
  'sf_path_info_key' => 'PATH_INFO',
  'sf_url_format' => 'PATH',
));

Refer to Chapter 19 for the meanings of the settings found in the settings.yml file.

Custom Application Settings and app.yml

Most of the settings related to the features of an application should be stored in the app.yml file, located in the myproject/apps/myapp/config/ directory. This file is environment-dependent and empty by default. Put in every setting that you want to be easily changed, and use the sfConfig class to access these settings from your code. Listing 5-19 shows an example.

Listing 5-19 - Sample app.yml to Define Credit Card Operators Accepted for a Given Site

all:
  creditcards:
    fake:             off
    visa:             on
    americanexpress:  on

dev:
  creditcards:
    fake:             on

To know if the fake credit cards are accepted in the current environment, get the value of:

[php]
sfConfig::get('app_creditcards_fake');

TIP Each time you are tempted to define a constant or a setting in one of your scripts, think about if it would be better located in the app.yml file. This is a very convenient place to store all application settings.

When your need for custom parameters becomes hard to handle with the app.yml syntax, you may need to define a syntax of your own. In that case, you can store the configuration in a new file, interpreted by a new configuration handler. Refer to Chapter 19 for more information about configuration handlers.

Tips for Getting More from Configuration Files

There are a few last tricks to learn before writing your own YAML files. They will allow you to avoid configuration duplication and to deal with your own YAML formats.

Using Constants in YAML Configuration Files

Some configuration settings rely on the value of other settings. To avoid setting the same value twice, symfony supports constants in YAML files. On encountering a setting name (one that can be accessed by sfConfig::get()) in capital letters enclosed in % signs, the configuration handlers replace them with their current value. See Listing 5-20 for an example.

Listing 5-20 - Using Constants in YAML Files, Example from autoload.yml

autoload:
  symfony:
    name:           symfony
    path:           %SF_SYMFONY_LIB_DIR%
    recursive:      on
    exclude:        [vendor]

The path parameter will take the value returned by sfConfig::get('sf_symfony_lib_dir'). If you want one configuration file to rely on another, you need to make sure that the file you rely on is already parsed (look in the symfony source to find out the order in which the configuration files are parsed). app.yml is one of the last files parsed, so you may rely on others in it.

Using Scriptable Configuration

It may happen that your configuration relies on external parameters (such as a database or another configuration file). To deal with these particular cases, the symfony configuration files are parsed as PHP files before being passed to the YAML parser. It means that you can put PHP code in YAML files, as in Listing 5-21.

Listing 5-21 - YAML Files Can Contain PHP

all:
  translation:
    format:  <?php echo (sfConfig::get('sf_i18n') == true ? 'xliff' : 'none')."\n" ?>

But be aware that the configuration is parsed very early in the life of a request, so you will not have any symfony built-in methods or functions to help you.

Also, as the echo language construct does not add a carriage return by default, you need to add a "n" or use the echoln helper to keep the YAML format valid.

all:
  translation:
    format:  <?php echoln sfConfig::get('sf_i18n') == true ? 'xliff' : 'none' ?>

CAUTION In the production environment, the configuration is cached, so the configuration files are parsed (and executed) only once after the cache is cleared.

Browsing Your Own YAML File

Whenever you want to read a YAML file directly, you can use the sfYaml class. It is a YAML parser that can turn a YAML file into a PHP associative array. Listing 5-22 presents a sample YAML file, and Listing 5-23 shows you how to parse it.

Listing 5-22 - Sample test.yml File

house:
  family:
    name:     Doe
    parents:  [John, Jane]
    children: [Paul, Mark, Simone]
  address:
    number:   34
    street:   Main Street
    city:     Nowheretown
    zipcode:  12345

Listing 5-23 - Using the sfYaml Class to Turn a YAML File into an Associative Array

[php]
$test = sfYaml::load('/path/to/test.yml');
print_r($test);

Array(
  [house] => Array(
    [family] => Array(
      [name] => Doe
      [parents] => Array(
        [0] => John
        [1] => Jane
      )
      [children] => Array(
        [0] => Paul
        [1] => Mark
        [2] => Simone
      )
    )
    [address] => Array(
      [number] => 34
      [street] => Main Street
      [city] => Nowheretown
      [zipcode] => 12345
    )
  )
)

Summary

The symfony configuration system uses the YAML language to be simple and readable. The ability to deal with multiple environments and to set parameters through a definition cascade offers versatility to the developer. Some of the configuration can be accessed from within the code via the sfConfig object, especially the application settings stored in the app.yml file.

Yes, symfony does have a lot of configuration files, but this approach makes it more adaptable. Remember that you don't need to bother with them unless your application requires a high level of customization.