Combien de temps prend la migration de Sylius 1.x vers 2.0 ?

Cela depend de la personnalisation de votre projet. Un projet avec moins de 10 overrides de templates et sans plugins custom prend 2 à 5 jours. Avec 10-30 overrides et 2-5 plugins, comptez 2 à 4 semaines. Pour un projet lourdement personnalisé (30+ overrides, passerelles de paiement custom), 1 à 3 mois.

Dois-je migrer vers Sylius 1.14 avant de passer à 2.0 ?

Oui, le guide officiel recommande de passer d'abord par Sylius 1.14 (la version LTS). Cela lisse les deprecations intermediaires et aligne votre codebase avec les dernieres APIs 1.x avant le saut vers 2.0.

Les template overrides fonctionnent-ils encore dans Sylius 2.0 ?

Oui, les overrides fonctionnent toujours mais sont deconseilles en faveur des Twig Hooks, un systeme ou vous enregistrez de petits fragments de templates à des points d'extension specifiques au lieu de copier des fichiers entiers.

Migrer Sylius 1.x vers 2.0 : Le Guide Complet

Sylius 2.0 est la release la plus significative depuis la creation du framework. Si vous exploitez une boutique Sylius 1.x en production, la migration n'est plus une question de si, mais de quand. Ce guide parcourt chaque domaine majeur de changement pour que vous puissiez planifier votre mise à jour en toute confiance.

Pourquoi Sylius 2.0 est un changement majeur

Sylius 2.0 n'est pas un simple composer update. L'equipe core à modernise l'ensemble du stack :

Frontend : Semantic UI + jQuery disparaissent, remplaces par Bootstrap 5 + Symfony UX (Turbo, Stimulus)
Templates : les Twig Hooks deviennent l'approche de personnalisation recommandee, remplacant l'ancien pattern de template overrides (toujours fonctionnel mais decourage)
Machines à etats : winzou/state-machine-bundle est remplace par Symfony Workflow
Mailer : SwiftMailer est remplace par symfony/mailer
Paiements : le flux base sur Payum est complete par le nouveau systeme Payment Requests (experimental en 2.0), qui remplacera progressivement Payum dans les prochaines versions mineures
API : API Platform 2.7 migre vers API Platform 4

Chacun de ces changements est un projet de migration en soi. Combines, ils peuvent representer des semaines ou des mois de travail selon le niveau de personnalisation de votre projet.

Etape 0 : Passer d'abord à Sylius 1.14

Si votre projet est sur Sylius 1.12 ou 1.13, montez d'abord sur 1.14 (la version LTS). Le guide officiel de migration recommande cela comme prerequis : cela lisse les deprecations intermediaires et aligne votre codebase avec les dernieres APIs 1.x avant d'attaquer le saut vers 2.0.

Etape 1 : Auditer vos template overrides

La plus grosse source d'effort de migration pour la plupart des projets, ce sont les overrides de templates Twig. Si vous avez surcharge 5 templates, c'est gerable. Si vous en avez surcharge 80, vous faites face à un effort significatif.

Dans Sylius 1.x, vous personnaliséz le storefront en placant des overrides dans templates/bundles/SyliusShopBundle/. Dans 2.0, les overrides fonctionnent toujours mais sont deconseilles en faveur des Twig Hooks, ou vous enregistrez de petits fragments de templates composables à des points d'extension specifiques au lieu de copier des fichiers entiers.

Ce qu'il faut faire :

Lister chaque template surcharge dans templates/bundles/
Pour chaque override, identifier ce que vous avez change (souvent ce ne sont que quelques lignes)
Mapper chaque changement vers le Twig Hook equivalent dans Sylius 2.0

Cet exercice de mapping est la partie la plus chronophage de l'audit. Chaque template surcharge doit etre analyse individuellement.

Etape 2 : Gerer les composants deprecies

winzou State Machine vers Symfony Workflow

Si vous avez defini des callbacks ou transitions custom de machine à etats, vous devrez les reecrire sous forme d'event subscribers Symfony Workflow. Le format de configuration est completement different.

Recherchez :

Les cles de configuration winzou_state_machine dans vos fichiers YAML
Les classes de callback custom
Tout service qui injecte StateMachineInterface

Note : le package winzou/state-machine-bundle à ete deplace dans les dependances suggerees de Sylius 2.0 et peut toujours etre installe manuellement si necessaire, mais tous les workflows core de Sylius ont migre vers Symfony Workflow.

SwiftMailer vers symfony/mailer

C'est generalement l'une des migrations les plus simples. La dependance swiftmailer/swiftmailer à ete completement supprimee (la librairie elle-meme à ete abandonnee par ses mainteneurs en 2021). Recherchez \Swift_Message, \Swift_Mailer, et toute configuration specifique à SwiftMailer, puis remplacez par les equivalents symfony/mailer.

Payum et Payment Requests

Sylius 2.0 introduit les Payment Requests comme architecture de paiement experimentale, event-driven, basee sur Symfony Messenger. En 2.0, Payum reste disponible et demeure le moyen par defaut d'interagir avec les passerelles de paiement : Payment Requests est concu pour fonctionner à ses cotes et le remplacer progressivement dans les prochaines versions mineures. Si vous avez ecrit des passerelles Payum custom, elles continuent de fonctionner, mais vous pouvez commencer à explorer Payment Requests pour les nouvelles passerelles ou les scenarios headless.

Etape 3 : Verifier la compatibilite des plugins

C'est une etape critique et souvent negligee. Chaque plugin tiers Sylius que vous utilisez doit etre compatible avec Sylius 2.0.

Pour chaque plugin dans votre composer.json :

Verifier si le plugin à une release compatible 2.x
Sinon, verifier les issues GitHub du plugin pour les plans de migration
Si aucun plan n'existe, vous devrez peut-etre forker le plugin ou trouver une alternative

Le statut varie plugin par plugin : certains (comme plusieurs plugins BitBag) ont deja des releases stables 2.x, d'autres sont en cours de portage, et quelques plugins communautaires plus petits n'ont pas de timeline annoncee. Verifiez toujours directement la page Packagist et le repo GitHub du plugin.

Etape 4 : Migration frontend

Si vous avez personnalisé le CSS ou le JavaScript du storefront, vous devrez migrer de Semantic UI vers Bootstrap 5. Cela signifie :

Remplacer les classes CSS Semantic UI (ui button, ui grid, etc.) par les equivalents Bootstrap
Reecrire tout code jQuery en controllers Stimulus
Mettre à jour votre configuration Webpack Encore (Sylius 2.0 utilise toujours Webpack Encore, avec une nouvelle organisation des assets)

Si votre projet utilise un frontend entierement custom (headless), cette etape peut ne pas s'appliquer.

Etape 5 : Migration API Platform

Si vous utilisez l'API de Sylius, vous devrez mettre à jour d'API Platform 2.7 vers 4. Les changements concrets incluent :

Les groupes de serialisation sont maintenant prefixes par sylius: (ex. admin:product:index devient sylius:admin:product:index). Les groupes non-prefixes ont ete supprimes, donc toute resource custom etendant les groupes Sylius doit etre mise à jour.
Les DataProviders deviennent des StateProviders et les DataPersisters deviennent des StateProcessors, suivant le pattern provider/processor d'API Platform 4. Les namespaces changent en consequence : les classes sous Sylius\Bundle\ApiBundle\DataProvider se deplacent vers Sylius\Bundle\ApiBundle\StateProvider.
Les DataTransformers disparaissent, certains refactores en SerializerContextBuilders.
Les fichiers de configuration des resources utilisent un nouveau schema XML (metadata/resources-3.0).

Estimation de l'effort

D'experience, voici un cadre d'estimation :

Type de projet	Niveau de personnalisation	Effort estime
Personnalisation legere	<10 overrides, pas de plugins custom	2 à 5 jours
Personnalisation moyenne	10 à 30 overrides, 2-5 plugins, state machines custom	2 à 4 semaines
Personnalisation lourde	30+ overrides, passerelles de paiement custom, JS custom important	1 à 3 mois

Ces estimations couvrent la migration du code applicatif uniquement. Ajoutez du temps pour les mises à jour d'infrastructure (runtime PHP 8.2+, Node.js 20 ou 22), la QA en regression complete, et la coordination avec les parties prenantes.

Automatiser l'audit

Faire cette analyse manuellement pour chaque projet est fastidieux et source d'erreurs. C'est exactement pourquoi j'ai construit Sylius Upgrade Analyzer : un outil CLI qui scanne votre projet Sylius 1.x et produit un rapport de migration detaille. Il verifie les overrides de templates, les composants deprecies, la compatibilite des plugins, les dependances frontend, et calcule une estimation d'effort en heures.

Le CLI est open-source (licence MIT) et s'execute entierement sur votre machine, votre code ne quitte jamais votre environnement. Si vous avez besoin d'un rapport PDF soigne pour les parties prenantes, un service payant optionnel est aussi disponible.

Points cles à retenir

Commencez l'audit maintenant, meme si vous n'etes pas pret à migrer. Comprendre le perimetre tot evite les surprises.
Les template overrides sont le plus gros facteur de risque. Concentrez votre evaluation la-dessus en premier.
Verifiez la compatibilite des plugins avant de vous engager sur un calendrier. Un seul plugin incompatible peut bloquer toute la migration.
Automatisez ce que vous pouvez. L'audit manuel sur des dizaines de fichiers, c'est la que les erreurs arrivent.

Sylius 2.0 est un bond en avant majeur pour la plateforme. L'effort de migration est reel, mais le resultat est un stack plus moderne et maintenable, compatible avec Symfony 6.4 LTS et Symfony 7. Planifiez en amont, et vous vous en sortirez sans encombre.