Installation de Symfony UX
Mise en place de Symfony UX, pas à pas dans un projet vierge
Notions théoriques
Ce qui se passe lors de l'installation de Symfony UX
Installer Symfony UX ne se résume pas à exécuter une commande Composer.
L'installation de Symfony UX un processus en plusieurs couches qui implique à la fois l'écosystème PHP et l'écosystème JavaScript.
Comprendre ce qui se passe, à chaque étape de l'installation de Symfony UX, permet de diagnostiquer les problèmes et d'éviter les erreurs classiques.
Voici les grandes étapes que l'on va détailler :
- Créer un projet Symfony vierge
- Installer le bundle Stimulus (base de Symfony UX)
- Configurer AssetMapper (le gestionnaire d'assets moderne)
- Installer un premier composant UX
- Vérifier que tout fonctionne
Prérequis sur Windows
Avant de commencer, plusieurs outils doivent être disponibles sur la machine :
PHP 8.1 minimum Symfony UX requiert PHP 8.1 ou supérieur. Sur Windows, PHP peut être installé via XAMPP, Laragon, ou directement depuis https://windows.php.net/download.
Composer Composer est le gestionnaire de dépendances PHP. Il est indispensable pour installer Symfony et ses composants. Téléchargement : https://getcomposer.org/Composer-Setup.exe.
Symfony CLI (recommandé) Le CLI Symfony facilite la création de projets et le lancement d'un serveur de développement local. Téléchargement : https://symfony.com/download.
Git Git est nécessaire pour que Composer puisse récupérer certains packages. Téléchargement : https://git-scm.com/download/win.
Sur Windows, après chaque installation d'un outil en ligne de commande (PHP, Composer, Symfony CLI), il faut fermer et rouvrir le terminal pour que les nouvelles variables d'environnement soient prises en compte.
Le rôle de Symfony Flex dans l'installation
Symfony Flex est un plugin Composer installé automatiquement dans tout projet Symfony. Son rôle est d'exécuter des recettes (recipes) lors de l'installation de packages.
Concrètement, quand on exécute composer require symfony/ux-chartjs, Symfony Flex :
- Télécharge le package PHP
- Installe automatiquement le package JavaScript associé (
@symfony/ux-chartjs) - Met à jour le fichier
assets/controllers.jsonpour activer le contrôleur Stimulus - Peut créer ou modifier des fichiers de configuration
Les recettes Symfony Flex sont hébergées sur https://flex.symfony.com. On peut y consulter exactement ce que chaque recette modifie dans un projet.
AssetMapper : le gestionnaire d'assets moderne
Depuis Symfony 6.3, AssetMapper est la solution recommandée pour gérer les fichiers JavaScript et CSS. Il remplace Webpack Encore dans les nouveaux projets.
Son fonctionnement est radicalement différent de Webpack :
| Webpack Encore | AssetMapper |
|---|---|
| Nécessite Node.js | Ne nécessite pas Node.js |
| Compile et bundle les fichiers JS | Sert les fichiers JS directement |
| Étape de build obligatoire | Pas d'étape de build |
| Configuration complexe | Configuration minimale |
| Supporte JSX, Vue SFC, TypeScript | Supporte JavaScript moderne (ESM) |
AssetMapper exploite les Import Maps, une fonctionnalité native des navigateurs modernes qui permet d'importer des modules JavaScript sans bundler.
Pour vérifier que votre navigateur supporte les Import Maps, consultez https://caniuse.com/import-maps. Tous les navigateurs modernes (Chrome, Firefox, Safari, Edge) les supportent depuis 2023.
La structure des assets dans un projet Symfony UX
Après installation de Symfony UX avec AssetMapper, voici les fichiers clés à connaître :
assets/
├── app.js ← Point d'entrée JavaScript principal
├── controllers/ ← Vos contrôleurs Stimulus personnalisés
│ └── hello_controller.js ← Exemple de contrôleur
├── controllers.json ← Déclaration des contrôleurs UX tiers
└── styles/
└── app.css ← Feuille de style principale
config/
└── packages/
└── asset_mapper.yaml ← Configuration d'AssetMapper
importmap.php ← Déclaration des dépendances JavaScript (équivalent package.json)
Le fichier controllers.json est particulièrement important : c'est lui qui active ou désactive les contrôleurs Stimulus fournis par les composants UX installés.
Le fichier importmap.php est l'équivalent du package.json pour AssetMapper. Il liste les dépendances JavaScript et leurs URLs CDN.
Contrairement à Webpack Encore, AssetMapper ne crée pas de dossier node_modules. Les dépendances JavaScript sont soit téléchargées localement dans assets/vendor/, soit référencées via un CDN dans importmap.php.
Le fichier app.js et le bootstrap de Stimulus
Le fichier assets/app.js est le point d'entrée de l'application JavaScript. Dans un projet Symfony UX, il contient typiquement :
import './bootstrap.js';
import './styles/app.css';
Et le fichier assets/bootstrap.js (généré automatiquement) initialise Stimulus :
import { startStimulusApp } from '@symfony/stimulus-bundle';
const app = startStimulusApp();
C'est cette ligne qui démarre le moteur Stimulus et charge tous les contrôleurs déclarés dans controllers.json ainsi que ceux présents dans le dossier assets/controllers/.
Si le fichier bootstrap.js n'importe pas startStimulusApp, aucun contrôleur Stimulus ne fonctionnera, qu'il soit personnalisé ou fourni par un composant UX. C'est l'une des erreurs les plus fréquentes lors d'une installation manuelle.
Les 2 façons d'installer Symfony UX
Option 1 — Projet vierge avec AssetMapper (recommandée)
symfony new mon-projet --webapp
cd mon-projet
composer require symfony/ux-stimulus-bundle
La commande --webapp crée un projet Symfony complet avec Twig, Doctrine, et AssetMapper préconfigurés.
Option 2 — Ajout à un projet existant avec Webpack Encore
composer require symfony/webpack-encore-bundle
npm install
composer require symfony/ux-stimulus-bundle
npm install --force
Dans ce cours, nous travaillons avec AssetMapper (option 1), qui est la méthode recommandée pour les nouveaux projets depuis Symfony 6.3.
Test de mémorisation/compréhension
TP pour réfléchir et résoudre des problèmes
L'objectif de ce TP est d'installer Symfony UX dans un projet vierge, en suivant chaque étape de configuration jusqu'à obtenir une page de test fonctionnelle avec le composant Chart.js opérationnel.
Étape 1 — Vérifier les prérequis
Avant de créer le projet, vérifiez que tous les outils nécessaires sont disponibles sur votre machine Windows.
Ouvrez VS Code, puis ouvrez un terminal et exécutez successivement les commandes suivantes :
php --version
composer --version
symfony version
git --version
Pour chaque commande, notez la version affichée. Si l'une d'elles n'est pas reconnue, installez l'outil manquant avant de continuer.
Vérifier les versions AVANT de créer le projet évite les erreurs cryptiques en cours de route. Un PHP trop ancien (< 8.1) bloquera l'installation de Symfony UX. Un Composer absent empêchera tout téléchargement. Cette étape prend 30 secondes et peut faire gagner plusieurs heures de débogage.
Étape 2 — Créer le projet Symfony dans le dossier Documents
Dans le terminal de VS Code, naviguez vers votre dossier Documents et créez le projet Symfony :
cd %USERPROFILE%\Documents
symfony new tp-symfony-ux --webapp
cd tp-symfony-ux
code .
Attendez la fin de la création du projet (cela peut prendre une à deux minutes selon votre connexion), puis vérifiez que VS Code s'ouvre bien sur le nouveau dossier tp-symfony-ux.
Le flag --webapp est le moyen le plus rapide de démarrer avec Symfony UX :
il préconfigure AssetMapper, Twig et le bundle Stimulus en une seule commande.
Sans ce flag, symfony new crée un micro-framework sans templates ni gestionnaire d'assets.
Étape 3 — Vérifier la configuration d'AssetMapper
Dans VS Code, ouvrez successivement les fichiers suivants et vérifiez leur contenu :
Fichier 1 : config/packages/asset_mapper.yaml
Fichier 2 : importmap.php (à la racine du projet)
Fichier 3 : assets/app.js
Fichier 4 : assets/bootstrap.js
Pour chaque fichier, notez ce qu'il contient et comprenez son rôle avant de passer à l'étape suivante.
startStimulusApp() est la fonction qui démarre tout l'écosystème Symfony UX.
Sans elle dans bootstrap.js, aucun contrôleur Stimulus ne se charge — ni les vôtres
dans assets/controllers/, ni ceux fournis par les composants UX installés.
C'est la première chose à vérifier si un composant ne répond pas.
Étape 4 — Configurer la connexion à MariaDB
Ouvrez le fichier .env à la racine du projet. Recherchez la ligne commençant par DATABASE_URL= et modifiez-la pour correspondre à votre installation MariaDB locale.
Pour connaître votre version exacte de MariaDB, exécutez dans le terminal :
mysql --version
Notez le numéro de version affiché, puis adaptez la ligne DATABASE_URL en conséquence. Créez ensuite la base de données avec la commande appropriée.
La valeur serverVersion dans DATABASE_URL doit correspondre exactement à votre version
de MariaDB ou MySQL. Symfony l'utilise pour générer du SQL compatible. Une version incorrecte
peut provoquer des erreurs silencieuses lors des migrations. Toujours vérifier
avec mysql --version avant de configurer le projet.
Étape 5 — Installer le composant ux-twig-component
Installez le composant ux-twig-component via Composer et observez attentivement ce que Symfony Flex affiche dans le terminal pendant l'installation.
composer require symfony/ux-twig-component
Une fois l'installation terminée, ouvrez le fichier assets/controllers.json et notez son contenu.
Tous les composants Symfony UX ne sont pas des contrôleurs JavaScript. ux-twig-component
ajoute uniquement la capacité de créer des composants Twig réutilisables côté PHP.
Si controllers.json ne change pas après installation d'un composant UX, c'est souvent
voulu — vérifier la documentation du composant pour savoir s'il apporte un contrôleur Stimulus.
Étape 6 — Installer le composant ux-chartjs
Installez maintenant le composant ux-chartjs et vérifiez les modifications apportées automatiquement par Symfony Flex dans deux fichiers clés.
composer require symfony/ux-chartjs
Une fois l'installation terminée, ouvrez et comparez le contenu de assets/controllers.json et de importmap.php par rapport à leur état précédent.
Après chaque composer require d'un composant Symfony UX, prenez l'habitude de vérifier les fichiers assets/controllers.json et importmap.php. Ces deux fichiers sont modifiés automatiquement par la recette Symfony Flex : le premier active le contrôleur Stimulus, le second enregistre les dépendances JavaScript. Les comprendre permet de diagnostiquer rapidement pourquoi un composant ne se charge pas dans le navigateur.
Étape 7 — Créer une page de test et lancer le serveur
Créez un contrôleur Symfony dédié aux tests, vérifiez que le template généré étend bien base.html.twig, puis lancez le serveur de développement et accédez à la page dans votre navigateur.
php bin/console make:controller TestController
Après la génération, ouvrez templates/base.html.twig et vérifiez la présence de la balise {{ importmap('app') }} dans le <head>. Lancez ensuite le serveur :
symfony server:start
Accédez à https://127.0.0.1:8000/test et ouvrez la console du navigateur avec F12 pour vérifier l'absence d'erreurs JavaScript.
La balise {{ importmap('app') }} dans le <head> est le point d'entrée de tout l'écosystème JavaScript d'AssetMapper. Sans elle, aucun fichier JS n'est chargé : ni Stimulus, ni les contrôleurs UX, ni les styles. Dans un projet --webapp, elle est présente par défaut dans base.html.twig, mais si vous créez un layout personnalisé, pensez toujours à l'y inclure.
Étape 8 — Confirmer que Chart.js est bien chargé
Pour valider que le composant ux-chartjs est réellement opérationnel et non simplement installé, inspectez le code source de la page depuis le navigateur et identifiez la balise <script> qui charge le contrôleur Stimulus de Chart.js.
Dans votre navigateur, accédez à https://127.0.0.1:8000/test, puis affichez le code source de la page (Ctrl + U).
Recherchez dans le code source les occurrences de chartjs ou importmap et notez ce que vous observez.
Afficher le code source de la page (Ctrl+U) est une technique de débogage essentielle avec AssetMapper. Le bloc <script type="importmap"> généré par Symfony liste exactement les modules disponibles côté navigateur. Si un composant UX n'apparaît pas dans cette liste, c'est qu'il n'est pas dans importmap.php — soit l'installation a échoué, soit la recette Flex n'a pas été exécutée. C'est le premier endroit à inspecter avant tout autre diagnostic.
Une solution
Vous devez être connecté pour voir le contenu.