Migrer vers Sylius 2 progressivement : le Legacy Bridge
Oui, on peut migrer vers Sylius 2 en deux temps grâce au LegacyShopBridgePlugin, un plugin officiel qui permet de garder la boutique 1.x, son thème Semantic UI et ses template events, sur un cœur Sylius 2. On migre d'abord le cœur et l'administration, puis on réécrit le front page par page. Mais le plugin est expérimental, seul le cœur de Sylius est garanti compatible, et il ne dispense ni du travail sur le paiement, ni de celui sur l'API.
Je suis développeur Sylius et Symfony indépendant à Metz, et j'ai déjà mené des montées de version Sylius 1.x vers 2.x de boutiques en production. Ce qui suit repose sur le dépôt officiel du plugin, sa fiche sur le Sylius Store et sa page Packagist, consultés début novembre 2026.
Pourquoi le front bloque-t-il la plupart des migrations vers Sylius 2 ?
Parce que c'est la partie la plus personnalisée d'une boutique, et celle que Sylius 2 change le plus. Le guide UPGRADE-2.0 remplace Semantic UI et jQuery par Bootstrap 5 et Symfony UX, supprime SyliusUiBundle, les template events et Sonata Block, et introduit les Twig Hooks et les Twig Components. Chaque gabarit surchargé, chaque bloc injecté par un événement, chaque script jQuery de votre thème est à reprendre.
Sur une boutique au design travaillé, ce chantier front pèse souvent autant que tout le reste réuni. Le pont sert à le sortir du chemin critique : vous pouvez passer le cœur en 2.x sans attendre que le nouveau thème soit prêt. Je détaille la réécriture elle-même dans l'article sur la migration du front vers Bootstrap et Stimulus.
Que fait exactement le LegacyShopBridgePlugin ?
Selon son README, il permet à une application Sylius 2 d'utiliser le front de boutique de Sylius 1.x. Concrètement, il rétablit quatre choses. La fonction Twig sylius_template_event et le système de blocs de SyliusUiBundle 1.x. Les contrôleurs de boutique supprimés en 2.0 pour le panier, les commandes et le changement de devise ou de langue. L'intégration des blocs Sonata dans les gabarits. Et des filtres Twig historiques comme sort_by.
La fiche du Sylius Store précise qu'il fonctionne à côté du nouveau front de Sylius 2 et qu'on peut migrer page par page, à son rythme. C'est ce point qui rend la migration progressive possible.
Ce que l'installation implique
L'installation n'est pas un simple composer require. Le README demande d'activer SonataBlockBundle, FOSRestBundle et JMSSerializerBundle, c'est-à-dire des briques que Sylius 2 a justement retirées. Il faut renommer la configuration sylius_ui en sylius_legacy_shop_bridge, ajouter des chemins Twig qui doivent passer en dernier, charger les routes du plugin après celles de la boutique, et déclarer ses contrôleurs de commande, de ligne de commande et de province, ou ajouter ses traits si vous les aviez déjà surchargés. Côté assets, il faut une seconde configuration Webpack Encore nommée legacy.shop, avec jQuery, Semantic UI, lightbox2 et slick-carousel, et réécrire les chemins build/shop/ en build/legacy/shop/. Enfin, quelques fonctions Twig comme sylius_order_items_subtotal ou sylius_product_variant_prices doivent être remplacées par leurs équivalents modernes, et le menu sylius.shop.account devient sylius_shop.account. Votre thème n'est donc pas repris tel quel : il est adapté à la marge.
Comment se déroule une migration en deux temps, admin d'abord puis front ?
Le plugin ne couvre que la boutique. L'administration, elle, passe directement sur la nouvelle interface de Sylius 2. Le découpage logique est donc le suivant.
| Étape | Ce qui change | Ce que voient vos clients |
|---|---|---|
| 1. Montée en 1.14 | Version de départ alignée, dépréciations supprimées | Rien |
| 2. Cœur et admin en 2.x | Symfony Workflow, Payment Requests, API Platform 4, symfony/mailer, nouvelle administration | La même boutique, servie par le pont |
| 3. Mise en production | Bascule du cœur, recette du tunnel de commande | Toujours l'ancien thème |
| 4. Réécriture du front | Pages refaites en Twig Hooks et Bootstrap, une par une | Nouvelles pages au fil des livraisons |
| 5. Retrait du pont | Suppression du plugin, de FOSRest, JMS et Sonata Block | Une boutique entièrement en 2.x |
L'étape 2 reste lourde. Le pont ne touche ni aux machines à états, ni au paiement, ni à l'API. Les articles sur la migration de winzou vers Symfony Workflow et sur les Payment Requests décrivent ce travail, qu'il faut faire dans tous les cas. Votre équipe change aussi d'administration dès l'étape 3 : prévoyez de la former et de migrer vos écrans d'administration sur mesure avant la bascule.
Quelles sont les limites du plugin ?
La première est son statut. Sa documentation est rangée dans la section expérimentale de docs.sylius.com, et ses versions publiées vont de 0.1.0 à 0.1.3, la dernière datée du 10 avril 2026 sur Packagist. Un outil en 0.1 peut changer, et rien ne promet sa maintenance à long terme.
La deuxième concerne les plugins tiers. La documentation officielle indique que la compatibilité n'est garantie que pour le cœur de Sylius ; les plugins tiers demandent des ajustements au cas par cas. La fiche du Store est plus précise : un plugin déjà mis à jour pour Sylius 2 affiche ses vues avec des Twig Hooks, pas avec des template events, et il faudra peut-être adapter ses vues de boutique au système historique. Autrement dit, chaque plugin qui ajoute quelque chose au front doit être vérifié. La méthode est détaillée dans le guide de vérification des plugins.
La troisième est la version cible. Le fichier Composer accepte sylius/sylius ^2.0, mais la fiche du Store affiche une compatibilité de 2.0 à 2.2. Sylius 2.3, sortie le 28 septembre 2026, demande PHP 8.3 et accepte Symfony 8.0. Tant que la compatibilité du pont avec votre cible n'est pas vérifiée sur une copie, je ne la considère pas acquise.
La dernière est la dette. Vous gardez jQuery, Semantic UI et trois bundles retirés du cœur. Chaque montée de version suivante devra être testée avec eux. Le pont achète du temps ; il ne supprime pas le travail.
Quand faut-il utiliser le pont, et quand faut-il l'éviter ?
| Situation | Mon conseil |
|---|---|
| Thème très personnalisé, peu de plugins qui touchent au front | Bon candidat : le cœur passe vite en 2.x, le front suit ensuite |
| Échéance de sécurité proche et refonte graphique prévue de toute façon | Bon candidat : on ne réécrit pas un thème qu'on va jeter |
| Nombreux plugins tiers qui injectent des blocs dans la boutique | Prudence : chaque plugin devra être adapté aux template events |
| Thème proche du thème par défaut | Inutile : la migration directe du front coûte moins que le pont |
| Aucune date prévue pour réécrire le front | À éviter : le provisoire deviendra définitif, avec sa dette |
Le calendrier pèse aussi. Selon endoflife.date, la 1.14 ne reçoit plus de correctifs de sécurité après le 31 décembre 2026. Pour une boutique au thème lourd, le pont peut être le moyen le plus réaliste de passer le cœur sur une branche maintenue à temps, à condition de viser une version encore supportée et de valider la compatibilité du plugin avec elle.
Comment savoir si votre boutique s'y prête ?
Il faut mesurer deux choses : le poids du front par rapport au reste, et le nombre de plugins qui interviennent dans la boutique. C'est ce que fait Sylius Upgrade Analyzer, l'outil open source que j'ai créé. Exécuté en local, il compte vos gabarits surchargés et vos usages de template events, recense vos dépréciations, vérifie vos plugins sur le Sylius Store et Packagist, et produit un rapport exploitable par votre équipe. Il ne décide pas pour vous : il vous donne les chiffres qui permettent de comparer une migration directe et une migration en deux temps. Pour la vue d'ensemble du chemin, voyez le guide complet de la migration 1.x vers 2.x.
Si vous voulez un avis argumenté, je lance l'analyse sur votre projet et je vous remets un diagnostic offert, avec une estimation en jours pour les deux scénarios. Si le pont ne vous fait rien gagner, je vous le dirai.