Migrating Sylius 1.x to 2.0: A Complete Guide

Sylius 2.0 is the most significant release since the framework's inception. If you're running a Sylius 1.x store in production, migration is no longer a question of if but when. This guide walks you through every major area of change, so you can plan your upgrade with confidence.

Why Sylius 2.0 Is a Major Shift

Sylius 2.0 isn't a simple composer update. The core team has modernized the entire stack. Here's what's changing at a high level:

• Frontend: Semantic UI + jQuery are gone, replaced by Bootstrap 5 + Symfony UX (Turbo, Stimulus)
• Templates: The old Twig template override system gives way to Twig Hooks, a more composable approach
• State machines: winzou/state-machine-bundle is replaced by Symfony Workflow
• Mailer: SwiftMailer is out, symfony/mailer is in
• Payments: Payum is being phased out for the new Payment Requests system
• API: API Platform 3 migrates to API Platform 4

Each of these is a migration project in itself. Combined, they can represent weeks or months of work depending on how heavily your project has customized the default Sylius behavior.

Step 1: Audit Your Template Overrides

The biggest source of migration effort for most projects is Twig template overrides. If you've overridden 5 templates, it's manageable. If you've overridden 80, you're looking at a significant effort.

In Sylius 1.x, you override templates by placing files in templates/bundles/SyliusShopBundle/. In 2.0, this system is replaced by Twig Hooks, where you register small, composable template blocks instead of copying entire files.

What to do:

1. List every template you've overridden in templates/bundles/
2. For each override, identify what you changed — often it's just a few lines
3. Map each change to the equivalent Twig Hook in Sylius 2.0

This mapping exercise is the most time-consuming part of the audit. Each overridden template needs to be analyzed individually.

Step 2: Handle Deprecated Components

winzou State Machine → Symfony Workflow

If you've defined custom state machine callbacks or transitions, you'll need to rewrite them as Symfony Workflow event subscribers. The configuration format is completely different.

Look for:

• winzou_state_machine configuration keys in your YAML files
• Custom callback classes
• Any service that injects StateMachineInterface

SwiftMailer → symfony/mailer

This is usually one of the easier migrations. Search for \Swift_Message, \Swift_Mailer, and any SwiftMailer-specific configuration. Replace with symfony/mailer equivalents.

Payum → Payment Requests

If you've written custom Payum gateways or extended the payment flow, this migration can be complex. The new Payment Requests system uses a completely different architecture.

Step 3: Check Plugin Compatibility

This is a critical and often overlooked step. Every third-party Sylius plugin you use needs to be compatible with Sylius 2.0.

For each plugin in your composer.json:

1. Check if the plugin has a 2.x-compatible release
2. If not, check the plugin's GitHub issues for migration plans
3. If no plans exist, you may need to fork the plugin or find an alternative

Common plugins like BitBag's CMS, shipping, and payment plugins are actively being updated, but smaller community plugins may lag behind.

Step 4: Frontend Migration

If you've customized the storefront's CSS or JavaScript, you'll need to migrate from Semantic UI to Bootstrap 5. This means:

• Replacing Semantic UI CSS classes (ui button, ui grid, etc.) with Bootstrap equivalents
• Rewriting any jQuery code as Stimulus controllers
• Updating your Webpack Encore configuration or moving to the new asset system

If your project uses a fully custom frontend (headless), this step may not apply.

Step 5: API Platform Migration

If you use Sylius's API, you'll need to update from API Platform 3 to 4. This primarily affects:

• Resource configuration (annotations/attributes may change)
• Custom data providers and processors
• Serialization groups

Estimating the Effort

From experience, here's a rough estimation framework:

Project Type	Customization Level	Estimated Effort
Light customization	< 10 template overrides, no custom plugins	2–5 days
Medium customization	10–30 overrides, 2–5 plugins, custom state machines	2–4 weeks
Heavy customization	30+ overrides, custom payment gateways, heavy JS	1–3 months

The key variables are: number of template overrides, number of deprecated API usages, and plugin compatibility.

Automating the Audit

Doing this analysis manually for each project is tedious and error-prone. That's exactly why I built Sylius Upgrade Analyzer — a CLI tool that scans your Sylius 1.x project and produces a detailed migration report. It checks template overrides, deprecated components, plugin compatibility, frontend dependencies, and calculates an effort estimation in hours.

The CLI is open-source (MIT license) and runs entirely on your machine — your code never leaves your environment. If you need a polished PDF report for stakeholders, there's also an optional paid service.

Key Takeaways

1. Start the audit now, even if you're not ready to migrate yet. Understanding the scope early avoids surprises.
2. Template overrides are the biggest risk factor. Focus your assessment there first.
3. Check plugin compatibility before committing to a timeline. A single incompatible plugin can block the entire migration.
4. Automate what you can. Manual auditing across dozens of files is where mistakes happen.

Sylius 2.0 is a major leap forward for the platform. The migration effort is real, but the result is a more modern, maintainable stack built on Symfony 7. Plan ahead, and you'll get there smoothly.