DEV Community: Pierre-Arthur DEMENGEL

Symfony 7 and Sylius 2.0: What Changes for Developers

Pierre-Arthur DEMENGEL — Sat, 11 Apr 2026 20:25:31 +0000

Sylius 2.0 supports both Symfony 6.4 LTS and Symfony 7.1+.

For developers who've been running Sylius 1.x on Symfony 5 or 6, this means a significant stack modernization. Let's break down what Symfony 7 brings to the table and what it means concretely for your Sylius projects.

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+, and Sylius 2.0 aligns with that minimum. 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.2 brings readonly classes and significant performance improvements, and if you move to PHP 8.3 you also get typed class constants and the json_validate() function.

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 has been removed (the library itself was abandoned by its maintainers in 2021). symfony/mailer is the standard replacement in Sylius 2.0.
Routing: Docblock annotations (@Route in comments, relying on SensioFrameworkExtraBundle) are no longer supported. Use PHP 8 attributes #[Route], which Symfony has supported since 5.2.
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 Become the Recommended Customization Approach

This change is Sylius-specific, provided by the sylius/twig-hooks package (which itself supports Symfony 6.4 and 7.x). The old pattern of overriding entire Twig templates by placing files in templates/bundles/ still works but is discouraged in favor of Twig Hooks: a system where you register small template fragments that hook into specific extension points.

Twig Hooks primarily replaces the older Sylius Template Events and Sonata Block Events systems. The benefit: your customizations are more granular and survive Sylius core updates more cleanly. The cost: existing template overrides need to be rewritten if you want to follow the new approach.

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

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.

Symfony UX Replaces jQuery

The frontend migration isn't just a Sylius decision: it 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 and Streams for partial page refreshes
The asset pipeline changes (Webpack Encore configuration updates; Sylius 2.0 still uses Webpack Encore)

API Platform 4

Sylius 2.0 moves from API Platform 2.7 to API Platform 4, which brings:

Simplified resource configuration (new XML schema metadata/resources-3.0)
State providers and processors replacing the older data providers and data persisters
Improved OpenAPI documentation generation
Improved JSON:API and GraphQL support at the API Platform level (note: Sylius 2.0 doesn't expose GraphQL endpoints by default, but you can enable them)

If you've written custom API Platform data providers, data persisters, or data transformers, they'll need to be rewritten as state providers, state processors, or serializer context builders. Namespaces change accordingly (for example, classes under Sylius\Bundle\ApiBundle\DataProvider move to Sylius\Bundle\ApiBundle\StateProvider). Sylius also prefixes all its serialization groups with sylius: in 2.0, so any custom resource that extends Sylius groups needs to be updated.

Practical Migration Path

Here's the approach I recommend:

Phase 1: Prepare on Sylius 1.x (1–2 weeks, depending on project state)

Before touching Sylius 2.0, clean up your current codebase:

Upgrade to the latest Sylius 1.x release (1.14 LTS if you're not already there)
Run PHPUnit with SYMFONY_DEPRECATIONS_HELPER=strict
Fix all Symfony deprecations: encoders → password hashers, annotations → attributes, SwiftMailer → symfony/mailer
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 state machine customizations
Check plugin compatibility
Inventory frontend customizations

This is where Sylius Upgrade Analyzer helps. The CLI tool automates this entire audit, scanning your codebase with 49 analyzers organized into 6 thematic families (Templates & Frontend, Deprecations & Breaking Changes, Plugins, Grid & Resource, API Platform, Security) and producing a report with effort estimations. It runs locally, so your code doesn't leave your machine.

Phase 3: Backend Migration (1–4 weeks)

Tackle backend changes in order of dependency:

Update composer.json to require Sylius 2.0
Migrate state machine configuration and callbacks
Update payment gateway integrations
Fix any remaining deprecated API usages

Phase 4: Frontend Migration (1–4 weeks)

This can often run in parallel with backend work:

Replace Semantic UI classes with Bootstrap 5
Convert jQuery code to Stimulus controllers
Update asset build configuration
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. Remember that plugin compatibility varies: some (like several BitBag plugins) already have stable 2.x releases, others are still being ported.

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.

Need help with your migration?

Developed by Pierre-Arthur Demengel, freelance developer specialised in Sylius 1.x to 2.x migrations. Need help migrating your store? Get a free diagnosis

Top 10 Mistakes When Migrating Sylius to 2.0

Pierre-Arthur DEMENGEL — Sat, 11 Apr 2026 20:21:01 +0000

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 6 thematic families (Templates & Frontend, Deprecations & Breaking Changes, Plugins, Grid & Resource, API Platform, Security), 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.

Need help with your migration?

Developed by Pierre-Arthur Demengel, freelance developer specialised in Sylius 1.x to 2.x migrations. Need help migrating your store? Get a free diagnosis

Migrating Sylius 1.x to 2.0: A Complete Guide

Pierre-Arthur DEMENGEL — Sat, 11 Apr 2026 20:18:32 +0000

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:

List every template you've overridden in templates/bundles/
For each override, identify what you changed (often it's just a few lines)
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. 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:

Check if the plugin has a 2.x-compatible release
If not, check the plugin's GitHub issues for migration plans
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. PDF reports for stakeholders are generated locally, for free (--format=pdf).

Key Takeaways

Start the audit now, even if you're not ready to migrate yet. Understanding the scope early avoids surprises.
Template overrides are the biggest risk factor. Focus your assessment there first.
Check plugin compatibility before committing to a timeline. A single incompatible plugin can block the entire migration.
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.

Need help with your migration?

Developed by Pierre-Arthur Demengel, freelance developer specialised in Sylius 1.x to 2.x migrations. Need help migrating your store? Get a free diagnosis

Sylius 1.x end of support is coming, so I built a CLI to audit your migration to 2.x

Pierre-Arthur DEMENGEL — Mon, 06 Apr 2026 06:04:36 +0000

Update, November 2026 (v2.5): every auto-fixer was replayed on real input and every rule checked against the Sylius 1.14 and 2.0 sources; wrong rules were corrected or removed, and each fixer now has a documented before/after example. Since v2.4 the tool also runs from a Docker image or a standalone PHAR, so it works whatever your project's PHP version. It is fully local and free, PDF reports included, every detection was re-checked against the official Sylius 2.0 sources, and it has been run on public Sylius projects (results below).

If you maintain a Sylius 1.x project in production, you already know what's coming. Sylius 1.14 is the final 1.x release: its maintenance ended in December 2025 and its security support ends in December 2026 (official release cycle). Every shop still running on 1.x will have to migrate to 2.x.

The official Sylius plugin migration guide is still tagged "WIP/experimental" on docs.sylius.com, and the scope of the upgrade is massive: Bootstrap + Symfony UX replacing Semantic UI + jQuery, Twig Hooks replacing template overrides, Symfony Workflow replacing winzou, symfony/mailer replacing SwiftMailer, Payment Requests introduced alongside Payum, API Platform 4 replacing API Platform 2.7, plus a long list of removed classes, renamed services, and dropped routes.

Every agency and every lead developer facing this migration does the same thing: open the project, manually dig through every overridden Twig template, check composer.json plugins one by one against the Marketplace, grep for jQuery calls, count Semantic UI classes, read through UPGRADE-2.0.md line by line. It takes days and the result is an approximate spreadsheet at best.

I found that unacceptable, so I built the tool that was missing.

What is Sylius Upgrade Analyzer

Sylius Upgrade Analyzer is an open-source CLI tool that scans a Sylius 1.x project and produces a full migration diagnostic in seconds. From the root of your project:

docker run --rm -v "$PWD:/project" ghcr.io/pierrearthurdemengel/sylius-upgrade-analyzer

That's it. No configuration needed, and nothing is installed in your project. It detects your Sylius version from composer.lock (or from composer.json when no lock is committed) and runs every analyzer against your codebase.

Compatibility

Supports every Sylius 1.x release, from 1.0 to 1.14 LTS (the final 1.x version). There is no Sylius 1.15 or 1.16. The default migration target is Sylius 2.2.

Works whatever your project's PHP version. The Docker image ships its own PHP, so a shop still on PHP 7.4 or Symfony 5.4 can be audited as is.

Installation

Pick the mode that fits. The first three never touch your project's composer.json.

# 1. Docker (recommended): any project PHP version, all formats including PDF
docker run --rm -v "$PWD:/project" ghcr.io/pierrearthurdemengel/sylius-upgrade-analyzer

# 2. Standalone PHAR: a single file, needs PHP 8.2+ on the machine running it (no PDF)
curl -LO https://github.com/pierrearthurdemengel/sylius-upgrade-analyzer/releases/latest/download/sylius-upgrade-analyzer.phar
php sylius-upgrade-analyzer.phar sylius-upgrade:analyze /path/to/project

# 3. Global Composer install
composer global require pierre-arthur/sylius-upgrade-analyzer

# 4. Inside the project, only if it already runs PHP 8.2+ with Symfony 6.4 or 7.x
composer require --dev pierre-arthur/sylius-upgrade-analyzer

The examples below use vendor/bin/sylius-upgrade-analyzer; with Docker, replace it with docker run --rm -v "$PWD:/project" ghcr.io/pierrearthurdemengel/sylius-upgrade-analyzer and pass /project as the path.

What It Covers

The tool ships with 49 built-in analyzers organized across 6 thematic families, all built from the official UPGRADE-2.0.md, UPGRADE-API-2.0.md, and CHANGELOG-2.0.md. Nothing is guessed, everything is sourced: detections that could not be traced back to a documented Sylius 2.0 change have been removed.

1. Templates & Frontend. Overridden Sylius templates that should migrate to Twig Hooks, sonata_block_render_event and sylius_template_event calls to replace with hook(), Semantic UI CSS classes still present in templates, jQuery and Semantic UI JS usage in assets, and webpack.config.js with @symfony/webpack-encore.

2. Deprecations & Breaking Changes. winzou state machine to Symfony Workflow, SwiftMailer to symfony/mailer, legacy user encoders to password_hashers, Payum gateways convertible to Payment Requests (optional: Payum is still supported in 2.0), message bus renames, the Message* namespaces of Sylius bundles renamed Command*, removed email managers, removed Stripe and PayPal Express Checkout gateways, service decorator targets, order processors and cart contexts no longer registered through their interface, form type extensions removed from the core, the removed api_security Behat service, listeners on the five removed admin menus, promotion rules, renamed shipping calculator services, Doctrine XML mapping to PHP attributes, fixture changes, the removed findOneByHostname() channel lookup, bundle configuration changes, sylius/calendar to symfony/clock, security firewall renames, removed user model fields, removed classes (150+), renamed service IDs, removed routes, LiipImagine config changes, changed constructor signatures, grid filter syntax changes, removed use_webpack config, PHP and Node version requirements, moved classes between bundles, service visibility changes, missing payment request env vars, and removed deprecated bundle packages like FOSRest and JMSSerializer.

3. Plugins. Cross-references every Sylius plugin in your composer.json against the Addons Marketplace API and Packagist to determine compatibility with 2.x, evaluating version constraints as real version ranges.

4. Grid & Resource. Custom grid YAML/PHP customizations (custom field types, filters and action templates), resource bundle config, repositories extending Sylius ones, service overrides in YAML and XML, grid filter entity syntax changes.

5. API Platform. Namespace changes, serialization group prefixes, endpoint restructuring, and query extension signature changes.

6. Security. The PHP version your project declares (Dockerfile, compose files, config.platform.php, .php-version, .tool-versions) is compared with the latest security releases. Runtimes below PHP 8.2.35, 8.3.36, 8.4.27 or 8.5.12 are exposed to CVE-2026-109618 and CVE-2026-109619, actively exploited remote code execution, and are reported as breaking.

Each issue is classified as BREAKING, WARNING, or SUGGESTION, with a time estimate in hours and a direct link to the relevant documentation.

Auto-fix

Detection is useful but fixing is better. The tool includes 37 auto-fixers that can apply the most common corrections automatically.

vendor/bin/sylius-upgrade-analyzer sylius-upgrade:analyze --fix --dry-run

The --dry-run flag generates a unified diff patch showing what would change without touching any files. When you're confident, drop the flag: in a terminal, the tool shows the full patch and asks for confirmation before writing anything (in CI it applies directly).

Fixers only rewrite files of your project: none of them connects to a database, runs a migration or executes a command, and none edits PHP payment code (the payment-related fixers only comment out obsolete YAML or add missing environment variables). Run it on a clean Git working tree and git diff shows exactly what changed.

Each fixer has a confidence level. HIGH means a rename or removal documented one-to-one in the official guides, like security.encoders to security.password_hashers or a renamed service ID. MEDIUM means correct but worth a check, like workflow migration or Sonata block event replacement. LOW is a starting point only. Use --min-confidence=high to apply only the safe ones. Every fixer's real before/after output is in docs/fixer-examples.md, replayed by the test suite on every run.

Among the 37 fixers: Twig Hook YAML generation, winzou to Symfony Workflow conversion, SwiftMailer to symfony/mailer rewrite, renamed service IDs, security firewall renames, LiipImagine config, Sonata block events to hook(), grid filter entity syntax, calendar-to-clock replacement, bundle config updates, deprecated package removal, routing import fixes, removed config keys, API namespace updates, and more.

Output Formats

The CLI supports six output formats depending on your workflow: Console (the default, with a colored ASCII gauge, severity breakdown and category table), JSON (machine-readable, for CI/CD integration), CSV (Excel-compatible with UTF-8 BOM and semicolon separator), SARIF (GitHub Code Scanning compatible), Markdown (human-readable, suitable for PRs and wikis), and PDF (detailed below).

vendor/bin/sylius-upgrade-analyzer sylius-upgrade:analyze --format=json --output=report.json

vendor/bin/sylius-upgrade-analyzer sylius-upgrade:analyze --format=sarif --output=report.sarif

vendor/bin/sylius-upgrade-analyzer sylius-upgrade:analyze --format=csv --output=report.csv

PDF Reports

The PDF report is generated locally, for free, and nothing leaves your machine. It is meant for decision makers: executive summary, risk factors, migration roadmap, detailed blocking issues, and an optional budget estimate based on your daily rate.

# Included in the Docker image; with Composer installs, add dompdf first
composer require --dev dompdf/dompdf

vendor/bin/sylius-upgrade-analyzer sylius-upgrade:analyze --format=pdf --output=report.pdf --tjm=600

The budget converts the estimated hours into days on a 7-hour basis, rounded up to the next half day.

Multi-Project Analysis

Agencies maintaining several Sylius shops can audit them in one run and get a comparison table (complexity, risk, blocking issues, hours, budget) with totals, as console output, JSON, Markdown or a consolidated PDF.

vendor/bin/sylius-upgrade-analyzer sylius-upgrade:multi-analyze \
  /path/to/shop-fr /path/to/shop-de --format=pdf --output=portfolio.pdf --tjm=600

GitHub Action

The analyzer runs in CI too. Add it to your workflow and it can fail on breaking issues, upload SARIF to GitHub Code Scanning, and post a summary comment on pull requests. The analyzer is installed outside your project, so your composer.json is left untouched.

permissions:
  contents: read
  security-events: write   # upload-sarif
  pull-requests: write     # post-pr-comment

steps:
  - uses: actions/checkout@v4
  - uses: pierrearthurdemengel/sylius-upgrade-analyzer@v2.4.0
    with:
      project-path: '.'
      target-version: '2.2'
      fail-on-breaking: 'true'
      upload-sarif: 'true'
      post-pr-comment: 'true'

Additional Features

The CLI also supports custom rules via a .sylius-upgrade-rules.yaml file at the root of your project, baseline management to save and diff results across runs, sprint planning with configurable team velocity, a plugin compatibility matrix, and report comparison to track migration progress.

Results on Public Projects

To check its findings against reality, the analyzer is run on public Sylius 1.x code bases, and every blocking issue is reviewed by hand:

Project	Issues	Blocking	Estimated effort
Sylius-Standard 1.14 (official skeleton)	66	27	52.0 h
Sylius/InvoicingPlugin 1.0	30	6	38.5 h
BitBag SyliusWishlistPlugin	13	2	15.5 h

Even an untouched skeleton needs real work. These runs also caught and fixed false positives in the analyzer itself. Details and reproduction commands are in docs/benchmarks.md.

Need help with your migration?

Developed by Pierre-Arthur Demengel, freelance developer specialised in Sylius 1.x to 2.x migrations. Need help migrating your store? Get a free diagnosis

DEV Community: Pierre-Arthur DEMENGEL

Symfony 7 and Sylius 2.0: What Changes for Developers

Symfony 7: What's Different

PHP 8.2 Minimum

All Deprecations Removed

New Attributes-First Approach

What This Means for Sylius 2.0

Twig Hooks Become the Recommended Customization Approach

Symfony Workflow Replaces winzou

Symfony UX Replaces jQuery

API Platform 4

Practical Migration Path

Phase 1: Prepare on Sylius 1.x (1–2 weeks, depending on project state)

Phase 2: Audit (1–2 days)

Phase 3: Backend Migration (1–4 weeks)

Phase 4: Frontend Migration (1–4 weeks)

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

The Bottom Line

Need help with your migration?

Top 10 Mistakes When Migrating Sylius to 2.0

1. Treating It Like a Regular Composer Update

2. Ignoring Template Overrides Until the Last Minute

3. Assuming All Plugins Are Compatible

4. Forgetting About winzou State Machine Callbacks

5. Not Testing Payment Flows

6. Underestimating the Frontend Migration

7. Migrating Everything at Once

8. Skipping the Deprecation Log

9. No Migration Roadmap

10. Doing the Entire Audit Manually

Bonus: Not Communicating the Effort to Stakeholders

Need help with your migration?

Migrating Sylius 1.x to 2.0: A Complete Guide

Why Sylius 2.0 Is a Major Shift

Step 0: Get to Sylius 1.14 First

Step 1: Audit Your Template Overrides

Step 2: Handle Deprecated Components

winzou State Machine → Symfony Workflow

SwiftMailer → symfony/mailer

Payum and Payment Requests

Step 3: Check Plugin Compatibility

Step 4: Frontend Migration

Step 5: API Platform Migration

Estimating the Effort

Automating the Audit

Key Takeaways

Need help with your migration?

Sylius 1.x end of support is coming, so I built a CLI to audit your migration to 2.x

What is Sylius Upgrade Analyzer

Compatibility

Installation

What It Covers

Auto-fix

Output Formats

PDF Reports

Multi-Project Analysis

GitHub Action

Additional Features

Results on Public Projects

Links

Need help with your migration?