Pierre-Arthur DEMENGEL

Posted on Apr 6 • Edited on Apr 16

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

#php #symfony #sylius

If you maintain a Sylius 1.x project in production, you already know what's coming. The end of support is approaching, and every site 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 installs via Composer, scans a Sylius 1.x project, and produces a full migration diagnostic in seconds.

composer require --dev pierre-arthur/sylius-upgrade-analyzer

vendor/bin/sylius-upgrade-analyzer sylius-upgrade:analyze

That's it. No configuration needed. It detects your Sylius version from composer.lock and runs every analyzer against your codebase.

Requirements

PHP 8.2 or higher
Symfony 6.4 or 7.2
A Sylius 1.x project (compatible with Sylius 1.0 and above)

What It Covers

The tool ships with 49 built-in analyzers organized across 5 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.

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 to Payment Requests, message bus renames, command handler namespace changes, removed email managers, removed payment gateways from core, service decorator targets, order processor priorities, form type extension priorities, deprecated Behat contexts, admin menu event changes, translation key renames, promotion rules, shipping calculators, Doctrine XML mapping to PHP attributes, fixture system changes, multi-store channel deprecations, 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.

4. Grid & Resource. Custom grid YAML/PHP customizations, resource bundle config, grid filter entity syntax changes.

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

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

Auto-fix

Detection is useful but fixing is better. The tool includes 41 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 and let it apply.

Each fixer has a confidence level. HIGH means safe to apply without review, like renaming security.encoders to security.password_hashers or updating removed service IDs. MEDIUM means likely correct but worth a manual check, like workflow migration or Sonata block event replacement.

Among the 41 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, translation key prefixes, 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

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.

- uses: pierrearthurdemengel/sylius-upgrade-analyzer@v1
  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, multi-project analysis for agencies managing several Sylius sites, report comparison to track migration progress, and webhook notifications.

PDF Reports

The sixth output format is PDF, generated via a web service at sylius-upgrade-analyzer.dev. This is the only paid part. Your source code never leaves your machine: the CLI sends the JSON report only, the service generates a professional PDF with migration roadmap and time estimates, and sends it back. No source code transits.

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

vendor/bin/sylius-upgrade-analyzer sylius-upgrade:upload report.json --api-key=sua_xxx --output=report.pdf

Three plans are available: Report at 59 EUR for a single PDF, Studio at 299 EUR per year for unlimited white-label reports with your agency's branding, and Agency at 799 EUR per year adding multi-seat keys and consolidated multi-project reports.

DEV Community