Christophe Meneses - Développeur
  • Liste des articles
  • Contact
  • Linkedin
  • Github
  • Flux RSS
Tous les articles PHP / Symfony Bonnes pratiques Symfony : la configuration
PHP Symfony

Bonnes pratiques Symfony : la configuration

Publié le 14/11/2015. Dernière mise à jour le 25/03/2018.

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: '...'

Autres articles sur les bonnes pratiques

  1. Création d'un projet
  2. La configuration
  3. Organiser sa logique métier
  4. Les contrôleurs
  5. Les templates
  6. Les formulaires
  7. L'internationalisation
  8. La sécurité
  9. Les ressources web
  10. Les tests
Début de l'article

Tous les articles PHP / Symfony Bonnes pratiques Symfony : la configuration

Liste des articles par catégorie

  1. Tous 124
  2. Apache2
  3. APC1
  4. Assetic2
  5. Bash2
  6. CentOS9
  7. Composer6
  8. CSS1
  9. Debian1
  10. Deployer1
  11. Design Pattern11
  12. Docker6
  13. Doctrine14
  14. Elasticsearch3
  15. Git6
  16. Google Charts1
  17. Hardware1
  18. Hébergement1
  19. JavaScript1
  20. jQuery4
  21. Kibana2
  22. Logstash1
  23. Machine Learning1
  24. MariaDB2
  25. Memcached2
  26. MySQL3
  27. Nginx2
  28. Panther3
  29. PHP59
  30. PHP_CodeSniffer1
  31. PHP-FPM2
  32. PhpMyAdmin1
  33. PhpStorm3
  34. PHPUnit6
  35. PostgreSQL2
  36. RabbitMQ2
  37. SQL1
  38. SVN4
  39. Sybase ASE1
  40. Symfony56
  41. Twig3
  42. Ubuntu14
  43. Vue.js2
  44. Vuex1
  45. Webpack Encore1
  46. Xdebug5

Derniers articles publiés

PHP
Différence entre les mots clés self et static dans le langage PHP

Symfony / Docker / Nginx
Migrer un projet Symfony du protocole HTTP 1.1 au protocole HTTP 2

Vue.js
Utiliser un filtre Vue.js directement dans le JavaScript

PHP / Symfony
Supprimer les messages de dépréciation de type : The "sensio_framework_extra.routing.loader.annot_*" service is deprecated since version 5.2

Symfony / RabbitMQ
Exemple d'utilisation du composant Messenger pour envoyer des emails en asynchrone avec RabbitMQ

PHP Symfony MariaDB HTML5 CSS3 JavaScript Bootstrap

© 2014 - 2019 réalisé par Christophe MENESES