Symfony UX : Qu’est-ce que c’est et Comment ça Fonctionne ?

Vous voulez ajouter du JavaScript moderne à votre projet Symfony sans vous compliquer la vie ? C’est le but de Symfony UX.

Ce guide vous montre comment l’installer et l’utiliser avec des exemples concrets, pour avoir des interfaces réactives rapidement.

Démarrage rapide : installer et utiliser Symfony UX en 2 minutes

Le moyen le plus simple de démarrer avec Symfony UX est d’utiliser le composant AssetMapper. C’est l’approche officielle et recommandée par Symfony car elle ne nécessite pas Node.js ni d’étape de compilation.

La première chose à faire, c’est d’installer les dépendances de base avec Composer. La commande suivante installe AssetMapper et le StimulusBundle de Symfony, l’approche recommandée aujourd’hui.

composer require symfony/asset-mapper symfony/stimulus-bundle

Une fois la commande exécutée, plusieurs fichiers et dossiers sont créés dans votre projet. Voici les plus importants :

• assets/bootstrap.js : Le fichier qui démarre Stimulus et charge vos contrôleurs.
• assets/app.js : Votre fichier JavaScript principal. C’est ici que vous importerez d’autres fichiers.
• assets/controllers.json : Configure les contrôleurs JavaScript tiers que vous installez. Il se met à jour tout seul.
• assets/controllers/hello_controller.js : Un exemple de contrôleur Stimulus pour vous aider à démarrer.
• assets/styles/app.css : Votre fichier CSS principal.

Un exemple concret : un convertisseur Markdown

Pour voir comment ça marche, créons un petit outil qui convertit du texte Markdown en HTML en temps réel. D’abord, le code HTML à placer dans un template Twig.

<div data-controller="markdown">
    <textarea
        data-markdown-target="input"
        data-action="markdown#render"
    >Writing _JavaScript_ is... a **dream** with Stimulus 🤩</textarea>
    <div data-markdown-target="preview">
        <small><- Write something in the textarea!</small>
    </div>
</div>

Ici, trois attributs sont importants :

• data-controller="markdown" : Cet attribut connecte ce bloc HTML au contrôleur JavaScript markdown_controller.js.
• data-markdown-target="..." : Il permet d’identifier des éléments spécifiques (la zone de texte et la prévisualisation) pour les manipuler en JS. On les appelle des « targets ».
• data-action="markdown#render" : Il déclenche la méthode render() de notre contrôleur à chaque fois que l’utilisateur écrit dans le textarea.

Maintenant, créons le contrôleur JavaScript dans assets/controllers/markdown_controller.js.

import { Controller } from '@hotwired/stimulus';
import snarkdown from 'snarkdown';

export default class extends Controller {
    static targets = ['input', 'preview'];

    render() {
        const rendered = snarkdown(this.inputTarget.value);
        this.previewTarget.innerHTML = rendered;
    }
}

Ce code est simple. La méthode render() récupère la valeur du textarea (grâce à this.inputTarget), la convertit avec la librairie snarkdown, puis injecte le HTML dans la div de prévisualisation (this.previewTarget). C’est tout. Aucune configuration complexe, juste des attributs HTML qui parlent au JavaScript.

Qu’est-ce que Symfony UX ? les principes fondamentaux

Symfony UX n’est pas un seul outil, mais deux choses à la fois. C’est avant tout une initiative open source. Son but est de construire un écosystème qui relie le monde de Symfony (PHP) à celui du JavaScript moderne. Le projet est sur GitHub et les contributions sont encouragées, que ce soit via des issues ou des Pull Requests.

C’est aussi un ensemble de librairies indépendantes. Vous n’êtes pas obligé de tout prendre. Vous pouvez simplement installer le package dont vous avez besoin, comme ux-chartjs pour des graphiques ou ux-typed pour des animations de texte. Chaque package est conçu pour fonctionner de manière autonome.

Comment ça fonctionne ? l’architecture sous le capot

Pour fonctionner, Symfony UX s’appuie sur deux technologies principales : un moteur JavaScript et un gestionnaire d’assets.

Le moteur JavaScript : Stimulus

Le cœur de Symfony UX est Stimulus, un petit framework JavaScript créé par l’équipe de Hotwire. Son approche est différente des gros frameworks comme React ou Vue. Au lieu de prendre le contrôle total de votre front-end, Stimulus cherche à enrichir votre HTML existant.

Le principe est simple : vous écrivez des contrôleurs JavaScript, puis vous les attachez à votre HTML via des attributs data-. C’est une façon de garder la logique de rendu côté serveur (avec Twig) tout en ajoutant de l’interactivité côté client de manière propre et organisée.

La gestion des assets : AssetMapper vs. Webpack Encore

Pour que le navigateur charge vos fichiers JS et CSS, Symfony a besoin d’un gestionnaire d’assets. Il y a deux options principales :

• AssetMapper : C’est l’option moderne et recommandée par Symfony. Elle est 100% PHP, ne crée pas de dossier node_modules et ne nécessite aucune étape de compilation (« build »). C’est la solution la plus simple et la plus directe.
• Webpack Encore : C’est l’option « historique ». Elle repose sur Node.js et Webpack, ce qui implique une étape de compilation pour transformer vos assets en fichiers lisibles par le navigateur. C’est plus puissant mais aussi plus complexe à configurer.

Pour la plupart des projets, AssetMapper est le meilleur choix pour démarrer avec Symfony UX. Il simplifie beaucoup le développement front-end.

Explorez l’écosystème : une sélection de packages incontournables

La vraie force de Symfony UX réside dans son écosystème de packages. Ils permettent d’ajouter des fonctionnalités riches à vos interfaces sans écrire une ligne de JavaScript (ou presque). Voici certains des plus populaires :

• Twig Component & Live Component : Ces deux packages travaillent ensemble. Twig Component permet de créer des composants réutilisables en PHP et Twig. Live Component les rend dynamiques : vous pouvez mettre à jour une partie de la page suite à une action utilisateur, le tout en écrivant uniquement du PHP. Parfait pour les formulaires avec des champs dépendants ou des tris de listes en temps réel.
• Turbo : Ce package intègre Hotwire Turbo pour transformer votre application en une expérience de type Single Page Application (SPA). Les clics sur les liens et les soumissions de formulaires sont interceptés en JavaScript, et seule la partie de la page qui change est mise à jour. L’application devient beaucoup plus rapide et fluide.
• UX Typed : Basé sur la librairie populaire Typed.js, ce package permet de créer des animations de texte avec un effet « machine à écrire ». Très simple d’utilisation pour dynamiser des titres ou des présentations.
• UX Chart.js : Permet de créer des graphiques interactifs (barres, camemberts, lignes…) directement depuis votre contrôleur PHP. Vous configurez vos données et vos options en PHP, et le package se charge de générer tout le JavaScript nécessaire pour afficher le graphique avec Chart.js.
• UX Icons : Simplifie l’intégration et la manipulation d’icônes SVG dans vos templates Twig. Fini les copier-coller de balises SVG, vous pouvez appeler une icône avec une simple fonction Twig.
• Frameworks JS (React, Vue, Svelte) : Si vous avez besoin d’intégrer des composants plus complexes, il existe des packages pour rendre des composants React, Vue ou Svelte directement depuis vos templates Twig, en leur passant des données depuis PHP.

Contribuer et aller plus loin

Symfony UX est une initiative communautaire. Si vous voulez aider à l’améliorer, proposer de nouvelles idées ou corriger des bugs, tout se passe sur GitHub. Chaque contribution, même petite, aide à faire grandir l’écosystème.

Le projet est sur GitHub pour ceux qui veulent participer.

En résumé, Symfony UX permet aux développeurs back-end de créer des interfaces modernes sans devenir des experts du front-end. C’est un pont efficace entre la puissance de PHP avec Symfony et la réactivité du JavaScript, qui rend le développement full-stack plus simple et plus agréable.