Chapitre 3.4 — Arborescence & configuration

Partie 3 : Installation & environnement — Chapitre 4/5 Version de référence : Symfony 7.4.

⏱️ TL;DR

• La config vit dans config/ : config/packages/*.yaml (un fichier par bundle), config/services.yaml (le conteneur), config/routes.yaml (routing hors attributs).
• Les variables d’environnement se déclarent dans .env (valeurs par défaut, committé) et se surchargent dans .env.local (secrets/machine, non committé).
• Trois environnements : dev (débogage + profiler), prod (optimisé + caché), test (pour PHPUnit). Pilotés par APP_ENV.
• On lit une variable d’env dans la config avec la syntaxe %env(NOM)%.
• Les vrais secrets (clés d’API, secret JWT) vont dans le coffre de secrets chiffré (secrets:set), pas dans .env.
• Pour un dev Next.js : .env / .env.local ≈ vos .env / .env.local Next, avec la même règle « on committe les valeurs par défaut, jamais les secrets ».

🎯 Objectifs

• Se repérer dans config/ et comprendre le rôle de chaque dossier.
• Manier .env, .env.local et la précédence des fichiers.
• Comprendre les environnements dev/prod/test et leur config spécifique.
• Savoir où mettre un secret (et où ne pas le mettre).

1. Le dossier config/

config/
├── bundles.php              ← liste des bundles activés (géré par Flex)
├── services.yaml            ← configuration du conteneur de services (Partie 5)
├── routes.yaml              ← routing global (souvent vide : on route par attributs)
├── routes/                  ← config de routing par bundle (ex. framework.yaml)
└── packages/
    ├── framework.yaml       ← config du FrameworkBundle
    ├── doctrine.yaml        ← config de Doctrine (après composer require orm)
    ├── security.yaml        ← config de la sécurité
    ├── twig.yaml            ← config de Twig
    └── dev/ , prod/ , test/ ← surcharges spécifiques à un environnement

Chaque bundle a son fichier dans config/packages/. Les sous-dossiers dev/, prod/, test/ contiennent des surcharges appliquées uniquement dans l’environnement correspondant (ex. config/packages/dev/web_profiler.yaml n’active la barre de debug qu’en dev).

⚡ Depuis Symfony 5 : la structure est stable, mais la tendance est au YAML pour la config d’infrastructure et aux attributs pour la config applicative (routes, mapping Doctrine, validation). Vous configurez les bundles en YAML dans config/packages/, mais vous ne mettez plus de routes ou de mapping d’entités dans des fichiers YAML séparés — tout ça est en attributs dans src/.

2. Les variables d’environnement : .env et ses amis

Symfony charge des variables d’environnement depuis une famille de fichiers .env, avec une précédence précise. L’idée directrice :

• .env — valeurs par défaut, committées dans git. Documente toutes les variables attendues.
• .env.local — surcharges locales (secrets, config machine), non committées (.gitignore l’exclut).
• .env.$env (.env.dev, .env.prod, .env.test) — valeurs par environnement, committées.
• .env.$env.local — surcharges locales par environnement, non committées.

Ordre de priorité (du plus fort au plus faible) : .env.$env.local > .env.local > .env.$env > .env. En clair : .env.local gagne toujours sur .env. C’est là que vous mettez votre DATABASE_URL réelle ou votre clé Stripe de dev.

Un .env typique :

# .env (valeurs par défaut, committé — PAS de vrais secrets ici)
APP_ENV=dev
APP_SECRET=change_me_in_env_local
DATABASE_URL="postgresql://app:!ChangeMe!@127.0.0.1:5432/app?serverVersion=16&charset=utf8"
MAILER_DSN=null://null

⚠️ Piège : ne mettez jamais un vrai secret dans .env (il est committé, donc public dans l’historique git). .env contient des valeurs par défaut/exemples ; les vraies valeurs sensibles vont dans .env.local (non committé) ou, mieux, dans le coffre de secrets (§5). Même règle qu’en Next.js : .env documenté, .env.local secret.

3. Lire une variable d’env dans la config : %env(...)%

Dans les fichiers YAML de config/, on injecte une variable d’environnement avec %env(NOM)% :

# config/packages/doctrine.yaml (extrait)
doctrine:
    dbal:
        url: '%env(resolve:DATABASE_URL)%'

On peut transformer la valeur avec des « processeurs » : %env(int:REDIS_PORT)%, %env(bool:FEATURE_X)%, %env(json:SOME_JSON)%, %env(resolve:...)% (résout d’autres paramètres). C’est le pont entre l’environnement (12-factor) et la configuration.

4. Les trois environnements

Symfony fait tourner la même application dans des configurations différentes selon APP_ENV :

On bascule via la variable APP_ENV (dans .env ou l’environnement système). En dev, APP_DEBUG=1 active le mode debug (rechargement du cache de config à chaque changement).

⚠️ Piège : oublier de passer en prod au déploiement. En dev, l’app est plus lente (recompile la config, active le profiler) et expose des détails d’erreur. En prod, toujours APP_ENV=prod APP_DEBUG=0, et composer install --no-dev --optimize-autoloader + bin/console cache:clear. On automatisera ça en Partie 15.

5. Les secrets : le coffre chiffré

Pour les vrais secrets (clé secrète d’app, secret JWT, clés d’API tierces), Symfony offre un coffre de secrets chiffré, versionnable sans exposer les valeurs :

# définir un secret (chiffré avec une clé publique ; la valeur n'est jamais en clair dans git)
php bin/console secrets:set STRIPE_SECRET_KEY
# lister
php bin/console secrets:list --reveal

Les secrets chiffrés vivent dans config/secrets/$env/. La clé de déchiffrement de prod (prod.decrypt.private.php), elle, n’est pas committée : elle est déployée séparément. On détaille ce mécanisme (et sa place dans une CI/CD) en Partie 15.

💡 Pour un dev Next.js : le coffre de secrets Symfony va plus loin que les .env de Next : les valeurs chiffrées peuvent être committées (seule la clé privée reste secrète), ce qui versionne la config sensible sans la divulguer. C’est un cran au-dessus de « mettre les secrets dans les variables d’env de Vercel ».

✏️ Exercices

Exercice 1. Où mettez-vous : (a) la valeur par défaut de DATABASE_URL documentée pour l’équipe ; (b) votre DATABASE_URL réelle de dev ; (c) la clé secrète Stripe de production ?

Exercice 2. Quel fichier .env a la priorité la plus forte, et quel est l’intérêt ?

Exercice 3. En dev, une modification de config/packages/twig.yaml n’est pas prise en compte. Quelle est la cause probable et la commande de secours ?

🧠 Quiz de révision

Prochain chapitre : 3.5 — Démarrer BookLab — on initialise le projet fil rouge, on connecte la base, on sert le premier écran et on fait le premier commit.