Top 10 des Erreurs lors de la Migration Sylius vers 2.0

Apres avoir aide plusieurs equipes à planifier leur migration Sylius 1.x vers 2.0, j'ai vu les memes erreurs revenir encore et encore. Voici les dix pieges les plus courants, et comment les eviter.

1. Traiter la migration comme un simple composer update

Sylius 2.0 n'est pas une montee de version mineure. Lancer composer update en esperant que tout fonctionne aboutira à une application cassee. C'est une migration de plateforme complete qui touche les templates, les state machines, le mailer, les paiements et le stack frontend.

Solution : Traitez-la comme un projet à part entiere avec du temps dedie, une branche specifique et un plan de tests.

2. Ignorer les template overrides jusqu'au dernier moment

Les overrides dans templates/bundles/SyliusShopBundle/ sont la source unique la plus importante de travail de migration. Dans Sylius 2.0, ces overrides fonctionnent toujours mais sont deconseilles en faveur des Twig Hooks. Beaucoup d'equipes repoussent cet inventaire et se retrouvent debordees par le volume de fichiers à convertir.

Solution : Faites un inventaire complet de vos overrides avant d'estimer l'effort de migration. Chaque override peut etre conserve tel quel (avec la dette technique associee) ou mappe vers l'equivalent Twig Hook (la voie recommandee).

3. Supposer que tous les plugins sont compatibles

Ce n'est pas parce qu'un plugin fonctionne sur Sylius 1.x qu'il à une release 2.0. Les auteurs de plugins doivent mettre à jour leur code pour la nouvelle architecture, et beaucoup ne l'ont pas encore fait.

Solution : Passez en revue chaque plugin Sylius de votre composer.json. Verifiez chacun sur le marketplace Sylius Addons et sur GitHub. Si un plugin n'a pas de version compatible 2.0 et pas de timeline annoncee, prevoyez un remplacement ou un fork.

4. Oublier les callbacks winzou State Machine

Si vous avez ajoute des callbacks custom à la configuration winzou_state_machine, ils ne fonctionneront pas avec Symfony Workflow. Le format de configuration, le systeme d'evenements et le mecanisme de guard sont tous differents : les guards passent des callbacks de service au langage d'expression de Symfony, et les callbacks deviennent des event subscribers.

Solution : Recherchez winzou_state_machine dans vos fichiers de config. Listez chaque callback et guard de transition custom. Chacun doit etre reecrit en event subscriber Symfony Workflow (ou guard en expression language pour les verifications d'autorisation simples).

5. Ne pas tester les flux de paiement

Sylius 2.0 introduit les Payment Requests comme architecture de paiement experimentale event-driven. En 2.0, Payum reste le moyen par defaut d'interagir avec les passerelles de paiement, donc les passerelles Payum custom existantes continuent de fonctionner, mais toute personnalisation touchant la logique de paiement doit etre retestee de bout en bout apres migration. Les passerelles supprimees du core (comme Stripe et PayPal Express Checkout, qui ne sont plus livrees avec Sylius par defaut) necessitent une attention particuliere.

Solution : Auditez votre repertoire Payum/ et tout code de passerelle custom. Verifiez si une passerelle dont vous dependez à ete supprimee du core. Testez chaque scenario de paiement dans votre environnement de staging apres migration, et ne supposez pas que "ca marche tout seul".

6. Sous-estimer la migration frontend

Passer de Semantic UI + jQuery à Bootstrap 5 + Symfony UX (Turbo + Stimulus), ce n'est pas juste swapper des classes CSS. Si votre storefront à des interactions JavaScript custom, des comportements de modales, des appels AJAX via jQuery, ou des composants Semantic UI custom, chacun doit etre reecrit.

Solution : Inventoriez chaque fichier .js et chaque template utilisant des classes Semantic UI. Estimez le travail frontend separement du travail backend : ils sont souvent comparables en effort.

7. Tout migrer en meme temps

Essayer de mettre à jour Symfony, Sylius, le frontend et tous les plugins simultanement cree un cauchemar de debug. Quand quelque chose casse, vous ne saurez pas quel changement l'a cause.

Solution : Si possible, montez d'abord sur la derniere Sylius 1.x (1.14 LTS) avec Symfony 6.4 LTS. Resolvez toutes les deprecations à ce stade. Puis attaquez la migration 2.0 comme une etape distincte.

8. Ignorer le log des deprecations

La couche de deprecation de Symfony existe pour une raison. Lancer votre application Sylius 1.x et verifier l'onglet deprecations du profiler Symfony vous dit exactement quelles APIs depreciees votre code utilise.

Solution : Lancez votre suite de tests avec SYMFONY_DEPRECATIONS_HELPER=strict dans PHPUnit. Corrigez chaque deprecation avant de commencer la migration 2.0. Cela supprime toute une categorie de surprises.

9. Pas de roadmap de migration

Commencer la migration sans plan structure mene au scope creep, aux developpeurs bloques et aux deadlines ratees. La migration touche chaque couche de l'application, elle necessite donc de la coordination.

Solution : Decoupez la migration en phases : audit, corrections des deprecations, migration backend, migration frontend, mise à jour des plugins, QA. Assignez des responsables et des timelines à chaque phase.

10. Faire l'audit entierement à la main

Verifier manuellement chaque override de template, chaque service deprecie, chaque version de plugin et chaque dependance frontend sur un gros projet est lent et source d'erreurs. Des problemes importants sont manques, les estimations d'effort sont inexactes, et les parties prenantes n'ont pas une vision claire.

Solution : Utilisez Sylius Upgrade Analyzer pour automatiser l'audit. Il scanne votre projet localement avec 49 analyseurs organises en 5 familles thematiques (Templates & Frontend, Deprecations & Breaking Changes, Plugins, Grid & Resource, API Platform), et produit un rapport structure avec des estimations d'effort en heures. Le CLI est open-source et votre code reste sur votre machine.

Bonus : Ne pas communiquer l'effort aux parties prenantes

La migration n'est pas qu'un sujet de developpeurs. Les product managers, chefs de projet et clients doivent comprendre que cela demandera du temps dedie et pourra temporairement ralentir la livraison de features.

Solution : Produisez un rapport de migration clair et visuel. Un PDF avec un score de complexite, une ventilation par categorie et des estimations en heures parle plus fort qu'un verbal "ca va prendre du temps". C'est exactement le type de livrable que Sylius Upgrade Analyzer génère.