Symfony 8.2 : un schéma JSON pour config/packages

Ce qui se passe

Symfony 7.4 avait doté services.yaml et routes.yaml de schémas JSON, ce qui permet à l'éditeur de compléter et de valider ces fichiers. Le dossier config/packages/, où se trouve l'essentiel de la configuration YAML, restait sans filet, pour une raison simple : chaque bundle définit son propre arbre, et le bon schéma dépend donc des bundles installés dans l'application.

Symfony 8.2 le calcule lui-même. Contribution de Jérôme Tamarelle.

Comment ça marche

Quand le conteneur est compilé en mode debug et que symfony/yaml est installé, Symfony écrit config/schema.json. Le fichier fusionne les arbres de configuration de tous les bundles enregistrés, blocs when@<env> compris, et il est régénéré à chaque compilation : il suit donc les bundles que vous ajoutez ou retirez. C'est l'équivalent YAML du config/reference.php apparu en 7.4 pour la configuration en PHP.

Brancher l'éditeur

L'éditeur ne trouve pas le fichier tout seul. Avec tout outil basé sur yaml-language-server (VS Code et son extension YAML, Neovim, Emacs), un commentaire en tête du fichier suffit. Exemple écrit pour cette fiche :

config/packages/framework.yamlYAML

# yaml-language-server: $schema=../schema.json
framework:
    secret: '%env(APP_SECRET)%'

Le chemin est relatif au fichier : ../../schema.json dans config/packages/<env>/. Pour couvrir tout le dossier d'un coup dans VS Code :

.vscode/settings.jsonJSON

{
    "yaml.schemas": {
        "./config/schema.json": "config/packages/**/*.yaml"
    }
}

Dans PhpStorm, la même correspondance se déclare dans Settings > Languages & Frameworks > Schemas and DTDs > JSON Schema Mappings. L'éditeur complète alors les noms d'options, affiche leur description et leur valeur par défaut, et signale une option inconnue, dépréciée ou d'un type incorrect.

Valider en CI

lint:yaml sait désormais confronter un fichier à un schéma, en plus de la syntaxe. Il faut la bibliothèque opis/json-schema :

Terminal

composer require --dev opis/json-schema
php bin/console lint:yaml config/ --check-schema

Les fichiers de config/packages/ sont vérifiés contre le schéma généré ; routes, services, serializer et validator contre les schémas de leurs composants ; un fichier sans schéma est déclaré valide. On peut donc lancer la commande sur tout config/.

Déduction de cette fiche, à vérifier sur votre chaîne : le schéma n'existant qu'après une compilation en debug, une CI qui démarre d'un dépôt propre doit réchauffer le cache en environnement de développement avant le lint.

La limite

Le schéma décrit l'arbre statique. Une valeur qu'un bundle n'accepte que grâce à une normalisation à l'exécution, par exemple une closure beforeNormalization() qui transforme une chaîne en liste, peut être signalée à tort. Lisez les premières erreurs avant de « corriger » une configuration qui fonctionnait.

Source : New in Symfony 8.2: JSON Schema for Configuration, blog Symfony, 23 septembre 2026.