Top 10 des Erreurs lors de la Migration Sylius vers 2.0

Après avoir accompagne plusieurs équipes dans la migration de Sylius 1.x vers 2.0, j'ai identifie des erreurs recurrentes. Voici les 10 pièges les plus frequents et comment les éviter.

1. Traiter la migration comme un simple composer update

Sylius 2.0 n'est pas une mise a jour mineure. Lancer composer update en esperant que tout fonctionne aboutira a une application cassee. Les changements affectent les templates, les state machines, le mailer, les paiements et le stack frontend.

Solution : Allouez du temps dédié, créez une branche spécifique, et définissez une stratégie de tests avant de commencer.

2. Ignorer les template overrides jusqu'au dernier moment

Les overrides dans templates/bundles/SyliusShopBundle/ representent le plus gros volume de travail. Les équipes sous-estiment systématiquement ce chantier.

Solution : Faites un inventaire complet de vos overrides avant d'estimer l'effort de migration. Chaque override peut rester tel quel (dette technique) ou être converti en Twig Hook.

3. Supposer que tous les plugins sont compatibles

La compatibilité des plugins n'est pas automatique. Les auteurs doivent mettre a jour leur code pour la nouvelle architecture, et beaucoup n'ont pas encore publie de version compatible.

Solution : Auditez chaque plugin Sylius de vos dependances. Vérifiez le marketplace Sylius Addons et GitHub. Prévoyez des remplacements ou des forks.

4. Oublier les callbacks winzou State Machine

Les callbacks personnalises de winzou_state_machine ne se transferent pas directement. Le format de configuration, le système d'événements et les mecanismes de guard différent fondamentalement.

Solution : Identifiez tous les callbacks et guards personnalises. Reecrivez chacun en event subscriber Symfony Workflow.

// Identifier les callbacks dans vos fichiers de config :
grep -r "winzou_state_machine" config/

5. Ne pas tester les flux de paiement

Sylius 2.0 introduit les Payment Requests, une architecture experimentale event-driven. Les passerelles Stripe et PayPal Express de base ont ete supprimees. Les implementations Payum personnalisees nécessitent un re-test complet.

Solution : Auditez votre repertoire Payum/ et votre code gateway personnalise. Testez chaque scénario de paiement en staging après migration.

6. Sous-estimer la migration frontend

Passer de Semantic UI + jQuery a Bootstrap 5 + Stimulus va au-dela du CSS. Les interactions JavaScript, les modales, les appels AJAX et les composants semantiques doivent tous être reecrits.

Solution : Inventoriez tous les fichiers JavaScript et templates utilisant Semantic UI. Estimez le travail frontend séparément — il est souvent comparable au travail backend.

7. Tout migrer en même temps

Mettre a jour Symfony, Sylius, les dependances frontend et les plugins simultanement créé une complexité de debug insurmontable.

Solution : Montez d'abord sur Sylius 1.14 LTS / Symfony 6.4 LTS. Corrigez toutes les deprecations. Puis attaquez la 2.0 comme une phase distincte.

8. Ignorer le log des deprecations

Les APIs depreciees cachent des problèmes de compatibilité qui emergeront pendant la migration.

Solution :

# Dans phpunit.xml.dist
SYMFONY_DEPRECATIONS_HELPER=strict

# Lancez vos tests
php bin/phpunit

Resolvez chaque deprecation avant de commencer la migration 2.0.

9. Pas de roadmap de migration

Commencer sans plan structure mene au scope creep, aux développeurs bloques et aux deadlines ratees.

Solution : Découpez en phases : audit, correction des deprecations, migration backend, migration frontend, mise a jour des plugins, QA. Assignez des responsables et des delais a chaque phase.

10. Faire l'audit entierement a la main

La vérification manuelle des overrides, services deprecies, versions de plugins et dependances frontend est lente et source d'erreurs sur les gros projets.

Solution : Utilisez Sylius Upgrade Analyzer, un outil CLI open-source avec 49 analyseurs produisant des rapports structures avec estimations en heures.

composer require --dev pierre-arthur/sylius-upgrade-analyzer
vendor/bin/sylius-upgrade-analyzer sylius-upgrade:analyze

Bonus : La communication avec les parties prenantes

La migration nécessite un engagement transversal. Product managers et chefs de projet doivent comprendre que cela demande du temps dédié et peut temporairement ralentir la livraison de features.

Solution : Créez des rapports visuels — PDFs avec scores de complexité, ventilation par catégorie et estimations en heures. L'Upgrade Analyzer génère ces livrables professionnels.

A retenir

Une migration Sylius 2.0 réussie exige de la traiter comme un projet dédié avec planification structuree, audit exhaustif, execution par phases et communication claire — pas comme une mise a jour de routine.