Bonnes pratiques Symfony : la configuration
Cette deuxième partie est une traduction personnelle des recommandations officielles sur la configuration d'un projet Symfony.
Symfony < 4.0
Attention si vous êtes sur une version plus récente, allez directement au chapitre pour les versions >= 4.0.
La configuration
La configuration concerne généralement les différentes parties d'une application (telles que l'infrastructure et les données de connexion) et les différents environnements (développement, production).
C'est pourquoi Symfony recommande que vous divisiez la configuration de l'application en trois parties.
Configuration de l'infrastructure
Définissez les paramètres de configuration de l'infrastructure dans le fichier app/config/parameters.yml.
Le fichier par défaut parameters.yml suit ces recommandations et définit la configuration de la base de données et du serveur d'email :
# app/config/parameters.yml
parameters:
database_driver: pdo_mysql
database_host: 127.0.0.1
database_port: ~
database_name: symfony
database_user: root
database_password: ~
mailer_transport: smtp
mailer_host: 127.0.0.1
mailer_user: ~
mailer_password: ~
# ...
Ces paramètres ne sont pas définis dans le fichier app/config/config.yml car ils n'ont rien à voir avec le comportement de l'application. Autrement dit, votre application ne se soucie pas de l'emplacement de votre base de données ou des identifiants de connexion pour y avoir accès, tant que la base de données est correctement configurée.
Paramètres canoniques
Définissez les paramètres de configuration de l'infrastructure dans le fichier app/config/parameters.yml.dist.
Depuis la version 2.3, Symfony inclut un fichier de configuration appelé parameters.yml.dist, qui stocke la liste canonique des paramètres de configuration de l'application.
À chaque fois qu'un nouveau paramètre de configuration est défini pour l'application, vous devriez l'ajouter aussi à ce fichier et soumettre les modifications à votre gestionnaire de version. Ensuite, chaque fois qu'un développeur met à jour le projet ou le déploie sur un serveur, Symfony va vérifier s'il y a une différence entre le fichier canonique parameters.yml.dist et votre fichier local parameters.yml. S'il y a une différence, Symfony vous demandera de fournir une valeur pour le nouveau paramètre et l'ajoutera à votre fichier local parameters.yml.
Configuration de l'application
Définissez les paramètres de configuration de l'application dans le fichier app/config/config.yml.
Le fichier config.yml contient les paramètres utilisés par l'application pour modifier son comportement, comme par exemple l'expéditeur des notifications par email, ou pour activer une feature toggles. Définir ces valeurs dans le fichier parameters.yml ajouterait une couche supplémentaire dans la configuration qui n'est pas nécessaire parce que vous n'avez pas besoin ou vous ne voulez pas que ces valeurs de configuration soient modifiées sur chaque serveur.
Les paramètres de configuration dans le fichier config.yml varient habituellement d'un environnement à un autre. C'est pourquoi Symfony inclut déjà les fichiers app/config/config_dev.yml et app/config/config_prod.yml afin que vous puissiez surcharger les valeurs spécifiques pour chaque environnement.
Constantes vs Paramètres de configuration
Une des erreurs les plus courantes lors de la définition de la configuration d'une application est de créer de nouveaux paramètres pour les valeurs qui ne changent jamais, comme le nombre d'éléments pour les résultats paginés.
Utilisez des constantes pour définir les paramètres de configuration qui changent rarement.
L'approche traditionnelle de définir des paramètres de configuration a poussé beaucoup d'application Symfony à inclure un paramètre comme celui ci-dessous, qui serait utilisé pour contrôler le nombre de messages à afficher sur la page d'accueil du blog :
# app/config/config.yml
parameters:
homepage.num_items: 10
Si vous avez fait quelque chose comme cela dans le passé, il est probable que vous ayez jamais réellement eu besoin de modifier cette valeur. Créer un paramètre de configuration pour une valeur que vous n'allez jamais modifier n'est tout simplement pas nécessaire. Notre recommandation est de définir ces valeurs comme des constantes dans votre application. Vous pourriez, par exemple, définir une constante NUM_ITEMS dans l'entité Post :
// src/AppBundle/Entity/Post.php
namespace AppBundle\Entity;
class Post
{
const NUM_ITEMS = 10;
// ...
}
Le principal avantage de définir des constantes est que vous pouvez utiliser leurs valeurs partout dans votre application. Quand on utilise des paramètres, ils sont uniquement accessibles dans les endroits qui ont accès au conteneur de Symfony.
Les constantes peuvent être utilisées par exemple dans vos templates Twig grâce à la fonction constant() :
<p>
Afficher les {{ constant('NUM_ITEMS', post) }} résultats les plus récents.
</p>
Et les entités et dépôts Doctrine peuvent facilement accéder à ces valeurs, alors qu'il ne peuvent pas accéder au conteneur de paramètre :
namespace AppBundle\Repository;
use Doctrine\ORM\EntityRepository;
use AppBundle\Entity\Post;
class PostRepository extends EntityRepository
{
public function findLatest($limit = Post::NUM_ITEMS)
{
// ...
}
}
Le seul inconvénient notable d'utiliser les constantes pour ce type de configuration est que vous ne pouvez pas les redéfinir facilement dans vos tests.
Configuration sémantique : à ne pas faire
Ne définissez pas une configuration d'injection de dépendance sémantique pour vos bundles.
Comme expliqué dans cette article, les bundles Symfony ont deux choix sur la façon de gérer leur configuration : une configuration normale des services à travers le fichier services.yml et une configuration sémantique à travers la classe spéciale Extension.
Bien que la configuration sémantique est beaucoup plus puissante et fournit des fonctionnalités intéressantes telles que la validation de la configuration, la quantité de travail nécessaire pour définir la configuration ne vaut pas la peine pour les bundles qui ne sont pas destinés à être partagés en tant que bundles tiers.
Déplacer les paramètres sensibles entièrement en dehors de Symfony
Lorsque vous manipulez des paramètres sensibles, comme les données de connexion à une base de données, nous vous recommandons également de les stocker en dehors du projet Symfony et de les rendre disponibles grâce à des variables d'environnement. Apprenez à le faire en lisant cet article.
Symfony >= 4.0
La configuration
La configuration concerne généralement les différentes parties d'une application (telles que l'infrastructure et les données de connexion) et les différents environnements (développement, production).
C'est pourquoi Symfony recommande que vous divisiez la configuration de l'application en trois parties.
Configuration de l'infrastructure
Il s'agit des paramètres qui varient d'une machine à une autre (par exemple de votre machine de développement au serveur de production) mais qui ne changent pas le comportement de l'application.
Définissez les paramètres de configuration de l'infrastructure dans des variables d'environnement. Pendant la phase de développement, utilisez le fichier .env à la racine du projet pour les définir.
Par défaut, Symfony ajoute ces types de paramètre dans le fichier .env quand il installe des nouvelles dépendances dans le projet :
# .env
###> doctrine/doctrine-bundle ###
DATABASE_URL=sqlite:///%kernel.project_dir%/var/data/blog.sqlite
###< doctrine/doctrine-bundle ###
###> symfony/swiftmailer-bundle ###
MAILER_URL=smtp://localhost?encryption=ssl&auth_mode=login&username=&password=
###< symfony/swiftmailer-bundle ###
# ...
Ces paramètres ne sont pas définis dans le fichier config/services.yml car ils n'ont aucun rapport avec le comportement de l'application. Autrement dit, votre application ne se soucie pas de l'emplacement de votre base de données ou des identifiants de connexion pour y avoir accès, tant que la base de données est correctement configurée.
Attention, quand on affiche le contenu des variables $_SERVER et $_ENV ou quand on fait un phpinfo(), les valeurs contenues dans les variables d'environnement vont être affichées. Il peut donc y avoir une fuite de données sensibles comme par exemple les paramètres de connexion à la base de données.
Paramètres canoniques
Définissez les paramètres de configuration de l'infrastructure dans le fichier .env.dist.
Symfony inclut un fichier de configuration appelé .env.dist, qui stocke la liste canonique des paramètres de configuration de l'application.
À chaque fois qu'un nouveau paramètre de configuration est défini pour l'application, vous devriez l'ajouter aussi à ce fichier et soumettre les modifications à votre gestionnaire de version. Ainsi les autres personnes sur le projet pourront mettre à jour leur fichier .env.
Configuration de l'application
Définissez les paramètres de configuration de l'application dans le fichier config/services.yml.
Le fichier services.yml contient les paramètres utilisés par l'application pour modifier son comportement, comme par exemple l'expéditeur des notifications par email, ou pour activer une feature toggles. Définir ces valeurs dans le fichier .env ajouterait une couche supplémentaire dans la configuration qui n'est pas nécessaire, parce que vous n'avez pas besoin ou vous ne voulez pas que ces valeurs de configuration soient modifiées sur chaque serveur.
Les paramètres de configuration dans le fichier services.yml varient habituellement d'un environnement à un autre. C'est pourquoi Symfony inclut déjà les fichiers config/services_dev.yml et config/services_prod.yml afin que vous puissiez surcharger les valeurs spécifiques pour chaque environnement.
Constantes vs Paramètres de configuration
Une des erreurs les plus courantes lors de la définition de la configuration d'une application est de créer de nouveaux paramètres pour les valeurs qui ne changent jamais, comme le nombre d'éléments pour les résultats paginés.
Utilisez des constantes pour définir les paramètres de configuration qui changent rarement.
L'approche traditionnelle de définir des paramètres de configuration a poussé beaucoup d'application Symfony à inclure un paramètre comme celui ci-dessous, qui est utilisé pour contrôler le nombre de messages à afficher sur la page d'accueil du blog :
# config/services.yml
parameters:
homepage.num_items: 10
Si vous avez fait quelque chose comme cela dans le passé, il est probable que vous ayez jamais réellement eu besoin de modifier cette valeur. Créer un paramètre de configuration pour une valeur que vous n'allez jamais modifier n'est tout simplement pas nécessaire. Notre recommandation est de définir ces valeurs comme des constantes dans votre application. Vous pourriez, par exemple, définir une constante NUM_ITEMS dans l'entité Post :
// src/Entity/Post.php
namespace App\Entity;
class Post
{
const NUMBER_OF_ITEMS = 10;
// ...
}
Le principal avantage de définir des constantes est que vous pouvez utiliser leurs valeurs partout dans votre application. Quand on utilise des paramètres, ils sont uniquement accessibles dans les endroits qui ont accès au conteneur de Symfony.
Les constantes peuvent être utilisées par exemple dans vos templates Twig grâce à la fonction constant() :
<p>
Afficher les {{ constant('NUMBER_OF_ITEMS', post) }} résultats les plus récents.
</p>
Et les entités et dépôts Doctrine peuvent facilement accéder à ces valeurs, alors qu'il ne peuvent pas accéder au conteneur de paramètre :
namespace App\Repository;
use App\Entity\Post;
use Doctrine\ORM\EntityRepository;
class PostRepository extends EntityRepository
{
public function findLatest($limit = Post::NUMBER_OF_ITEMS)
{
// ...
}
}
Le seul inconvénient notable d'utiliser les constantes pour ce type de configuration est que vous ne pouvez pas les redéfinir facilement dans vos tests.
Nommage des paramètres de configuration
Les noms des paramètres de configuration doivent être le plus court possible et doivent inclure un préfixe commun à toute l'application.
Utiliser app. comme préfixe est une pratique commune pour éviter les conflits de nom avec les paramètres de Symfony et des bundles tiers. Pour le reste du nom, utilisez un ou deux mots pour décrire la finalité du paramètre :
# config/services.yaml
parameters:
# ne faites pas ceci : 'dir' est trop générique et ne veut rien dire.
app.dir: '...'
# faites ceci : court mais facile à comprendre.
app.contents_dir: '...'
# Vous pouvez utiliser des points, des espaces soulignés, des tirets,...
# mais il faut rester uniforme et utiliser le même format pour tous les paramètres
app.dir.contents: '...'
app.contents-dir: '...'