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: Twig Hooks becomes the recommended customization approach, replacing the old template override pattern (still functional but discouraged)
• State machines: winzou/state-machine-bundle is replaced by Symfony Workflow
• Mailer: SwiftMailer is out, symfony/mailer is in
• Payments: the Payum-based flow is being complemented by the new Payment Requests system (experimental in 2.0), which will progressively replace Payum in upcoming minor versions
• API: API Platform 2.7 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 0: Get to Sylius 1.14 First

If your project is on Sylius 1.12 or 1.13, upgrade to 1.14 (the LTS version) first. The official Sylius migration guide recommends this as a prerequisite: it smooths out intermediate deprecations and aligns your codebase with the latest 1.x APIs before tackling the 2.0 jump.

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 customize the storefront by placing template overrides in templates/bundles/SyliusShopBundle/. In 2.0, overrides still work but are discouraged in favor of Twig Hooks, where you register small, composable template fragments at specific extension points 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

Note: the winzou/state-machine-bundle package has been moved to the suggested dependencies in Sylius 2.0 and can still be installed manually if needed, but the core Sylius workflows have all migrated to Symfony Workflow.

SwiftMailer → symfony/mailer

This is usually one of the easier migrations. The swiftmailer/swiftmailer dependency has been completely removed (the library itself was abandoned by its maintainers in 2021). Search for \Swift_Message, \Swift_Mailer, and any SwiftMailer-specific configuration, and replace with symfony/mailer equivalents.

Payum and Payment Requests

Sylius 2.0 introduces Payment Requests as an experimental, event-driven payment architecture on top of Symfony Messenger. In 2.0, Payum is still available and remains the default way to interact with payment gateways: Payment Requests is designed to work alongside it and progressively replace it in upcoming minor versions. If you've written custom Payum gateways, they keep working, but you can start exploring Payment Requests for new gateways or headless scenarios.

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

The status varies plugin by plugin: some (like several BitBag plugins) already have stable 2.x releases, others are still being ported, and a few smaller community plugins have no announced timeline. Always check the plugin's Packagist page and GitHub repo directly.

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 (Sylius 2.0 still uses Webpack Encore, with new asset organization)

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 2.7 to 4. The concrete changes include:

• Serialization groups are now prefixed with sylius: (e.g., admin:product:index becomes sylius:admin:product:index). Non-prefixed groups have been removed, so every custom resource extending Sylius groups needs to be updated.
• DataProviders become StateProviders and DataPersisters become StateProcessors, following API Platform 4's provider/processor pattern. Namespaces change accordingly: classes under Sylius\Bundle\ApiBundle\DataProvider move to Sylius\Bundle\ApiBundle\StateProvider.
• DataTransformers are gone, some refactored into SerializerContextBuilders.
• Resource configuration files use a new XML schema (metadata/resources-3.0; note that the "3.0" refers to the schema version, not API Platform's major version).

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 to 5 days
Medium customization	10 to 30 overrides, 2 to 5 plugins, custom state machines	2 to 4 weeks
Heavy customization	30+ overrides, custom payment gateways, heavy JS	1 to 3 months

These estimates cover application code migration only. Add time for infrastructure updates (PHP 8.2+ runtime, Node.js 20 or 22), full regression QA, and stakeholder coordination.

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, so 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 compatible with Symfony 6.4 LTS and Symfony 7. Plan ahead, and you'll get there smoothly.