Migration Sylius 1.x vers 2.0 : le plan d'action pragmatique pour ne pas perdre de ventes

Sylius 2.0 n'est pas une mise à jour de routine. C'est une refonte en profondeur du stack technique : frontend, moteur de templates, state machines, mailer, paiements, API… chaque couche a été modernisée. Pour un projet e-commerce en production, cela représente potentiellement plusieurs semaines de travail — avec un risque réel d'interruption de service si la migration est mal séquencée.

Cet article vous propose un plan d'action structuré, pensé à la fois pour les développeurs qui vont exécuter la migration et pour les décideurs qui doivent en mesurer l'impact business.

Source originale : Migrating Sylius 1.x to 2.0: A Complete Guide par Pierre-Arthur Demengel.

Ce qui change vraiment dans Sylius 2.0

Avant de planifier quoi que ce soit, il faut comprendre l'ampleur des ruptures :

• Frontend : Semantic UI + jQuery sont abandonnés au profit de Bootstrap 5 + Symfony UX (Turbo, Stimulus)
• Templates : le système d'override Twig classique laisse place aux Twig Hooks, une approche plus composable
• State machines : winzou/state-machine-bundle est remplacé par Symfony Workflow
• Mailer : SwiftMailer est supprimé au profit de symfony/mailer
• Paiements : Payum est progressivement abandonné pour le nouveau système de Payment Requests
• API : migration d'API Platform 3 vers API Platform 4

Chacun de ces points est un chantier à part entière. La combinaison de tous peut représenter plusieurs mois de travail sur un projet fortement personnalisé.

Phase 1 — Audit et priorisation (avant de toucher au code)

La première étape n'est pas technique : c'est un audit de l'existant.

Inventaire des overrides Twig

C'est généralement là que réside 60 à 70 % de l'effort de migration. En Sylius 1.x, les overrides se placent dans templates/bundles/SyliusShopBundle/. En 2.0, ce mécanisme disparaît au profit des Twig Hooks.

Action concrète : listez exhaustivement tous vos fichiers surchargés.

find templates/bundles -name "*.html.twig" | sort

Si vous avez moins de 10 fichiers modifiés, la migration est gérable en quelques jours. Si vous en avez 50 ou plus, prévoyez un sprint dédié par zone fonctionnelle (checkout, compte client, catalogue, etc.).

Cartographie des state machines personnalisées

Avez-vous défini des états ou transitions custom sur les commandes, expéditions ou paiements ? Chaque configuration winzou devra être réécrite en Symfony Workflow. L'API est différente, mais la puissance est supérieure — notamment pour les callbacks et les guards.

Dépendances tierces

Vérifiez la compatibilité de vos bundles et plugins Sylius avec la version 2.0. Certains ne sont pas encore portés. Bloquer une migration sur une dépendance non maintenue est un risque réel.

Phase 2 — Migration technique séquencée

Une fois l'audit réalisé, la migration doit être phasée pour éviter de tout casser d'un coup.

2a. Mailer et paiements en priorité

Ces deux couches ont un impact direct sur le chiffre d'affaires. Un email de confirmation qui ne part plus ou un webhook de paiement cassé, c'est une perte immédiate et mesurable.

• SwiftMailer → symfony/mailer : la migration est documentée et outillée. L'essentiel du travail porte sur la réécriture des Mailer et Email custom. Testez systématiquement les scénarios critiques : confirmation de commande, réinitialisation de mot de passe, facture.
• Payum → Payment Requests : c'est la migration la plus délicate. Le nouveau système est plus propre architecturalement, mais il casse la compatibilité avec les gateways Payum existantes. Vérifiez que votre PSP dispose d'un plugin compatible Sylius 2.0 avant de vous lancer.

2b. Templates et Twig Hooks

Les Twig Hooks permettent d'injecter du contenu dans des zones nommées sans surcharger le template entier. C'est plus robuste et plus maintenable à long terme, mais cela nécessite de repenser la logique d'override.

Stratégie recommandée : migrez les templates par tunnel de conversion (page produit → panier → checkout → confirmation). Cela vous permet de valider le parcours d'achat complet avant de passer au reste.

2c. Frontend Bootstrap 5 + Symfony UX

Si votre thème est fortement personnalisé, ce chantier peut être le plus long visuellement. Turbo et Stimulus changent la façon d'écrire les interactions JavaScript. L'approche progressive (remplacer jQuery morceau par morceau) est préférable à une réécriture totale en une seule fois.

2d. API Platform 4 et state machines

Si vous exposez une API (B2B, application mobile, intégration ERP), la migration vers API Platform 4 introduit des changements dans la configuration des resources et des opérations. Planifiez une phase de tests d'intégration avec vos consommateurs d'API avant la mise en production.

Phase 3 — Automatiser les tests et sécuriser le rollback

Une migration de cette ampleur sans filet de sécurité est une prise de risque inacceptable en production.

Tests automatisés : couvrez au minimum les parcours critiques avec Behat ou Cypress — ajout au panier, checkout, paiement, création de compte. Ces tests doivent passer sur l'ancienne version et servir de référence pour valider la nouvelle.

Stratégie de déploiement :

• Utilisez des feature flags ou un environnement de staging isolé pour valider chaque phase
• Préparez un script de rollback testé — pas une intention, un script exécutable
• Planifiez la bascule en dehors des pics de trafic (nuit, week-end hors périodes commerciales)

Monitoring post-migration : surveillez activement les erreurs 500, les abandons de panier et les échecs de paiement pendant les 48 à 72 heures suivant la mise en production.

Conclusion : une migration qui se planifie, pas qui s'improvise

Sylius 2.0 apporte des améliorations structurelles réelles — un frontend moderne, une architecture d'events plus propre, un système de paiements plus maintenable. Mais le chemin pour y arriver demande une planification rigoureuse.

Les équipes qui réussiront cette migration sont celles qui auront :

1. Audité leur code avant de toucher à quoi que ce soit
2. Séquencé la migration par criticité business plutôt que par facilité technique
3. Automatisé leurs tests de non-régression en amont
4. Prévu un plan de rollback opérationnel

Chez MulerTech, nous accompagnons les projets Symfony/PHP dans ce type de migration avec une approche outillée et progressive. Si vous avez un projet Sylius en production et que vous souhaitez évaluer l'effort de migration, contactez-nous.