After helping several teams plan their Sylius 1.x → 2.0 migration, I've seen the same mistakes come up again and again. Here are the ten most common pitfalls, and how to avoid them.
1. Treating It Like a Regular Composer Update
Sylius 2.0 is not a minor version bump. Running composer update and hoping for the best will leave you with a broken application. This is a full platform migration that touches templates, state machines, mailer, payments, and the frontend stack.
Fix: Treat it as a project in its own right with dedicated time, a fresh branch, and a proper test plan.
2. Ignoring Template Overrides Until the Last Minute
Template overrides in templates/bundles/SyliusShopBundle/ are the single largest source of migration work. In Sylius 2.0, these overrides still work but are discouraged in favor of Twig Hooks. Many teams postpone this inventory and get blindsided by the volume of files they'll eventually want to convert.
Fix: Run a full inventory of your template overrides before estimating the migration effort. Each override can be kept as-is (with technical debt) or mapped to the new Twig Hook equivalent (the recommended path forward).
3. Assuming All Plugins Are Compatible
Just because a plugin works on Sylius 1.x doesn't mean it has a 2.0 release. Plugin authors need to update their code for the new architecture, and many haven't done so yet.
Fix: Go through every Sylius plugin in your composer.json. Check each one on the Sylius Addons marketplace and on GitHub. If a plugin doesn't have a 2.0-compatible version and no announced timeline, plan for a replacement or a fork.
4. Forgetting About winzou State Machine Callbacks
If you've added custom callbacks to winzou_state_machine configuration, those won't work with Symfony Workflow. The configuration format, event system, and guard mechanism are all different: guards move from service callbacks to Symfony's expression language, and callbacks become event subscribers.
Fix: Search your config files for winzou_state_machine. List every custom callback and transition guard. Each one needs to be rewritten as a Symfony Workflow event subscriber (or expression-language guard, for simple authorization checks).
5. Not Testing Payment Flows
Sylius 2.0 introduces Payment Requests as an experimental, event-driven payment architecture. In 2.0, Payum remains the default way to interact with payment gateways, so existing custom Payum gateways keep working, but any customization touching payment logic should be retested end-to-end after migration. Removed core gateways (like Stripe and PayPal Express Checkout, which are no longer shipped with Sylius by default) need particular attention.
Fix: Audit your Payum/ directory and any custom gateway code. Check whether any gateway you rely on was removed from core. Test every payment scenario in your staging environment after migration, and don't assume it "just works."
6. Underestimating the Frontend Migration
Moving from Semantic UI + jQuery to Bootstrap 5 + Symfony UX (Turbo + Stimulus) isn't just swapping CSS classes. If your storefront has custom JavaScript interactions, modal behaviors, AJAX calls via jQuery, or custom Semantic UI components, each one needs to be rewritten.
Fix: Inventory every .js file and every template using Semantic UI classes. Estimate frontend work separately from backend work: they're often comparable in effort.
7. Migrating Everything at Once
Trying to upgrade Symfony, Sylius, the frontend, and all plugins simultaneously creates a debugging nightmare. When something breaks, you won't know which change caused it.
Fix: If possible, first upgrade to the latest Sylius 1.x (1.14 LTS) on Symfony 6.4 LTS. Resolve all deprecations there. Then tackle the 2.0 migration as a separate step.
8. Skipping the Deprecation Log
Symfony's deprecation layer exists for a reason. Running your Sylius 1.x app and checking the Symfony profiler's deprecation tab tells you exactly what deprecated APIs your code uses.
Fix: Run your test suite with SYMFONY_DEPRECATIONS_HELPER=strict in PHPUnit. Fix every deprecation before starting the 2.0 migration. This removes an entire class of surprises.
9. No Migration Roadmap
Starting the migration without a structured plan leads to scope creep, blocked developers, and missed deadlines. Migration touches every layer of the application, so it needs coordination.
Fix: Break the migration into phases: audit, deprecation fixes, backend migration, frontend migration, plugin updates, QA. Assign owners and timelines to each phase.
10. Doing the Entire Audit Manually
Manually checking every template override, every deprecated service, every plugin version, and every frontend dependency across a large project is slow and error-prone. Important issues get missed, effort estimates are inaccurate, and stakeholders don't get a clear picture.
Fix: Use Sylius Upgrade Analyzer to automate the audit. It scans your project locally with 49 analyzers organized into 5 thematic families (Templates & Frontend, Deprecations & Breaking Changes, Plugins, Grid & Resource, API Platform), and produces a structured report with effort estimations in hours. The CLI is open-source and your code stays on your machine.
Bonus: Not Communicating the Effort to Stakeholders
Migration isn't just a developer concern. Product managers, project managers, and clients need to understand that this will take dedicated time and may temporarily slow feature delivery.
Fix: Produce a clear, visual migration report. A PDF with a complexity score, a breakdown by category, and hour estimates speaks louder than a verbal "it'll take a while." This is exactly the kind of deliverable Sylius Upgrade Analyzer generates.
Top comments (0)