Symfony 7: What's Different

Symfony 7 was released in November 2023. It's the "clean" major version that removes everything deprecated in the 6.x cycle. If you've been ignoring deprecation notices, Symfony 7 is where they become fatal errors.

PHP 8.2 Minimum

Symfony 7 requires PHP 8.2+. Sylius 2.0 pushes this to PHP 8.3. If your production servers still run PHP 8.1, you'll need to upgrade your runtime first.

This is generally a good thing — PHP 8.3 brings readonly classes, typed class constants, the json_validate() function, and significant performance improvements.

All Deprecations Removed

Every method, class, and configuration option that was marked @deprecated in Symfony 6.x is gone in Symfony 7. The most impactful removals for Sylius projects include:

• Security: The old security.encoders configuration is removed. You must use security.password_hashers.

• Mailer: SwiftMailer integration is completely gone. symfony/mailer is the only option.

• Routing: Annotation-based routing with @Route is removed in favor of PHP attributes #[Route].

• DI: Some container configuration shortcuts have been removed.

New Attributes-First Approach

Symfony 7 doubles down on PHP attributes everywhere: routing, security voters, event subscribers, DI configuration. If your Sylius project still uses YAML or annotation-based configuration for custom controllers and services, now is the time to modernize.

What This Means for Sylius 2.0

Twig Hooks Replace Template Overrides

The old pattern of overriding entire Twig templates by placing files in templates/bundles/ is replaced by Twig Hooks — a system where you register small template fragments that hook into specific extension points.

The benefit: your customizations survive Sylius core updates. The cost: every existing template override needs to be rewritten.

Symfony Workflow Replaces winzou

Sylius 1.x relied on winzou/state-machine-bundle for order, payment, and shipping workflows. Sylius 2.0 uses Symfony's native Workflow component.

Key differences for developers:

• Configuration moves from winzou_state_machine to framework.workflows

• Callbacks become event subscribers listening to workflow.transition events

• Guards use Symfony's expression language instead of service callbacks

• The Workflow component has better tooling: the workflow:dump command generates visual diagrams

Symfony UX Replaces jQuery

The frontend migration aligns with the broader Symfony ecosystem direction. Symfony UX (Turbo + Stimulus) is the official approach to frontend interactivity in Symfony applications.

For Sylius developers, this means:

• No more jQuery dependency

• Interactive features use Stimulus controllers instead of inline JS

• Page updates use Turbo Frames/Streams for partial page refreshes

• The asset pipeline changes (Webpack Encore configuration updates)

API Platform 4

Sylius 2.0 moves to API Platform 4, which brings simplified resource configuration, better state providers and processors, improved OpenAPI documentation generation, and native JSON:API support improvements.

If you've written custom API Platform data providers or transformers, they'll need to be updated to the new provider/processor pattern.

Practical Migration Path

Here's the approach I recommend:

Phase 1: Prepare on Sylius 1.x (1–2 weeks)

Before touching Sylius 2.0, clean up your current codebase:

1. Upgrade to the latest Sylius 1.x release

2. Run PHPUnit with SYMFONY_DEPRECATIONS_HELPER=strict

3. Fix all Symfony deprecations: encoders → password hashers, annotations → attributes, SwiftMailer → symfony/mailer

4. Make sure your tests pass green

Phase 2: Audit (1–2 days)

Run a comprehensive audit of your project to understand the full migration scope: count template overrides, list winzou customizations, check plugin compatibility, inventory frontend customizations.

This is where Sylius Upgrade Analyzer helps. The CLI tool automates this entire audit, scanning your codebase for all 26 migration categories and producing a report with effort estimations. It runs locally — your code doesn't leave your machine.

Phase 3: Backend Migration (1–4 weeks)

Tackle backend changes in order of dependency:

1. Update composer.json to require Sylius 2.0

2. Migrate state machine configuration and callbacks

3. Update payment gateway integrations

4. Fix any remaining deprecated API usages

Phase 4: Frontend Migration (1–4 weeks)

This can often run in parallel with backend work:

1. Replace Semantic UI classes with Bootstrap 5

2. Convert jQuery code to Stimulus controllers

3. Update asset build configuration

4. Test all interactive features (cart, checkout, admin)

Phase 5: Plugin Updates & QA (1–2 weeks)

Update all plugins, run full regression tests, and validate payment flows.

The Bottom Line

Symfony 7 + Sylius 2.0 is a major modernization. The resulting stack is cleaner, more maintainable, and better aligned with the PHP ecosystem's direction. The migration effort is real but manageable with proper planning.

The biggest risk isn't any single change — it's underestimating the combined scope. Audit first, plan methodically, and you'll come out the other side with a much better codebase.

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. Many teams postpone this inventory and get blindsided by the sheer volume of files that need to be converted to Twig Hooks.

Fix: Run a full inventory of your template overrides before estimating the migration effort. Each override needs to be mapped to the new Twig Hook equivalent.

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.

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.

5. Not Testing Payment Flows

The migration from Payum to Payment Requests changes how payment gateways work internally. If you've customized any gateway (custom Payum actions, extensions, or API calls), those customizations won't port directly.

Fix: Audit your Payum/ directory and any custom gateway code. Test every payment scenario in your staging environment after migration — don't assume it "just works."

6. Underestimating the Frontend Migration

Moving from Semantic UI + jQuery to Bootstrap 5 + 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 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 — 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, checks 26 different migration categories (templates, deprecations, plugins, grids, resources, frontend, API), 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.

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:

• 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:

• 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, custom data providers and processors, and serialization groups.

Estimating the Effort

From experience, here's a rough estimation framework:

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.