Sylius 2 : garder l'ajout au panier sans Symfony UX ?
Pour conserver l'ajout au panier sans dépendre de Symfony UX dans Sylius 2, trois voies existent : écrire votre propre contrôleur Symfony qui reprend la logique du composant officiel, passer par la Shop API si votre front est séparé, ou garder temporairement l'ancienne boutique avec le LegacyShopBridgePlugin. Aucune ne demande de toucher au cœur. Mais il faut savoir qu'en Sylius 2, l'ajout au panier standard est un Live Component : s'en passer, c'est sortir du chemin officiel et en assumer la maintenance.
Je suis développeur Sylius indépendant et j'ai mené des montées de version 1.x vers 2.x de boutiques en production. Le bouton d'ajout au panier est le point le plus sensible d'une boutique : s'il casse, le chiffre d'affaires s'arrête. Cet article traite uniquement de lui. L'adaptation de l'ensemble de votre JavaScript à Symfony UX fait l'objet d'un article voisin sur l'adaptation du frontend existant.
Qu'est-ce qui a changé pour l'ajout au panier entre Sylius 1.x et 2 ?
En Sylius 1.x, le formulaire de la fiche produit envoyait ses données en Ajax vers la route sylius_shop_ajax_cart_add_item, gérée par le contrôleur OrderItemController, et un script jQuery affichait le résultat. Le guide officiel UPGRADE-2.0 liste cette route parmi celles qui sont supprimées, avec la route partielle sylius_shop_partial_cart_add_item. Elle était d'ailleurs marquée comme dépréciée dans la 1.14. Le contrôleur OrderItemController n'existe plus dans la branche 2.0 du dépôt.
À la place, Sylius 2 rend le formulaire par un composant, AddToCartFormComponent, déclaré comme Live Component. Son action addToCart soumet le formulaire, déclenche l'événement d'ajout au panier, enregistre le panier, ajoute le message de confirmation et redirige vers la page du panier. Le gabarit relie le formulaire à cette action par un attribut data-action qui appelle le contrôleur Stimulus live. Comme l'explique la documentation de Symfony UX Live Components, une action de ce type envoie une requête POST en Ajax depuis le navigateur. Sans le JavaScript de Symfony UX, le bouton standard ne fait donc plus rien d'utile.
Pourquoi vouloir se passer de Symfony UX pour le panier ?
Les raisons que j'entends sont légitimes. Certaines équipes ont un thème très personnalisé qu'elles veulent garder tel quel pendant la migration. D'autres ont un front séparé, en React ou en application mobile, qui n'utilise pas les gabarits Twig. D'autres encore veulent un ajout au panier qui fonctionne même si le JavaScript ne se charge pas, ou réduire la quantité de JavaScript chargée sur les fiches produits.
Il faut pourtant garder une chose en tête : le panier n'est pas le seul Live Component de la boutique Sylius 2. Le résumé du panier, le widget panier de l'en-tête et le formulaire d'adresse du tunnel de commande en sont aussi. Retirer Symfony UX de l'ajout au panier ne retire pas Symfony UX de la boutique. La question est donc souvent mieux posée ainsi : faut-il un ajout au panier qui ne dépende pas de Symfony UX, ou faut-il un front qui n'en dépende pas du tout ?
Comment ajouter au panier avec un contrôleur Symfony classique ?
C'est la solution que je recommande quand la boutique garde ses gabarits Twig. Elle consiste à écrire un contrôleur dans votre code qui fait exactement ce que fait l'action du composant officiel, avec un formulaire HTML classique envoyé en POST.
Le contrôleur récupère le panier courant par le contexte de panier de Sylius, crée un article pour le produit avec la fabrique d'articles de panier, construit la commande d'ajout avec la fabrique AddToCartCommandFactory, puis soumet le formulaire AddToCartType, dont le service s'appelle désormais sylius.form.type.order.add_to_cart. Si le formulaire est valide, il déclenche l'événement SyliusCartEvents::CART_ITEM_ADD, sur lequel un écouteur de Sylius ajoute l'article à la commande par le modificateur de commande, enregistre le panier, ajoute le message de confirmation et redirige vers la page du panier. Ce formulaire fonctionne sans aucun JavaScript. Si vous voulez éviter le rechargement de page, un simple appel fetch vers ce même contrôleur suffit, sans réintroduire jQuery.
Trois précautions sont indispensables. D'abord, le panier doit toujours venir du contexte de panier, jamais d'un identifiant envoyé par le navigateur : Sylius a corrigé dans ses versions 2.x des failles de contrôle d'accès autour du panier et du tunnel de commande, dont une qui permettait d'agir sur le panier d'un autre utilisateur, et votre contrôleur ne doit pas recréer ce risque. Ensuite, gardez le jeton CSRF du formulaire. Enfin, suivez les évolutions du composant officiel à chaque montée de version 2.x : depuis la 2.3, par exemple, de nouveaux événements sont déclenchés après l'enregistrement du panier, et un contrôleur maison ne les émet que si vous les ajoutez.
Les autres solutions : Shop API et pont legacy
Un front séparé passe par la Shop API
Si votre boutique est headless, Symfony UX n'entre pas en jeu. La Shop API de Sylius 2 expose une opération d'ajout d'article sur la ressource /shop/orders/{tokenValue}/items, alimentée par la commande AddItemToCart. Votre front React, Vue ou mobile l'appelle directement. Le passage à la nouvelle version d'API Platform impose en revanche de retester tous les appels, ce que je décris dans l'article sur l'API de Sylius.
Le LegacyShopBridgePlugin, pour gagner du temps
Le LegacyShopBridgePlugin permet de faire tourner l'ancienne boutique 1.x sur une application Sylius 2 et fournit des contrôleurs pour les fonctions de panier et de commande que la 2.0 a retirées. C'est une étape, pas une destination : il réinstalle jQuery et Semantic UI et retarde le travail de front plutôt que de le supprimer. J'en détaille les limites dans l'article sur la migration progressive.
| Solution | Quand la choisir | Ce qu'elle coûte |
|---|---|---|
| Live Component officiel | Boutique Twig qui adopte le front de Sylius 2 | Adapter le thème, rien à maintenir côté panier |
| Contrôleur Symfony maison | Boutique Twig qui veut un ajout au panier sans Symfony UX | Un contrôleur à écrire, tester et maintenir à chaque version |
| Shop API | Front headless ou application mobile | Retester tous les appels d'API |
| LegacyShopBridgePlugin | Migration du front en plusieurs étapes | Dette temporaire, front à refaire plus tard |
Le bon choix dépend de votre thème, de votre trafic et de votre équipe. Si vous voulez qu'on le fasse ensemble sur votre code, le diagnostic de migration Sylius 2 inclut la lecture du front et du tunnel de commande.
Comment tester l'ajout au panier après la migration ?
Quelle que soit la solution, testez l'ajout au panier comme un parcours de paiement : produit simple, produit à déclinaisons, produit en rupture, quantité maximale, client connecté et client invité, promotion appliquée au panier, puis passage complet jusqu'à la commande. Faites-le aussi avec le JavaScript désactivé si c'était votre objectif. Sur les boutiques que j'ai migrées, c'est le cas du client invité qui revient se connecter avec un panier déjà rempli qui révèle le plus souvent une différence de comportement.
Sylius Upgrade Analyzer, l'outil open source que j'ai créé et publié sur le Sylius Store, repère dans votre code et vos gabarits les références aux routes supprimées comme sylius_shop_ajax_cart_add_item, ainsi que le JavaScript jQuery, ce qui donne la liste de ce qui doit être repris avant même d'écrire la première ligne.
Ce que je vous propose
L'ajout au panier mérite une décision explicite, pas une découverte en recette. Le support de sécurité de Sylius 1.14 s'arrête le 31 décembre 2026 : choisir maintenant entre composant officiel, contrôleur maison ou Shop API laisse le temps de tester sérieusement le parcours qui fait vos ventes.
Je lance Sylius Upgrade Analyzer sur votre projet, je regarde votre fiche produit et votre tunnel de commande, et je vous remets un diagnostic offert avec la solution que je recommande et une estimation en jours.