Sylius 2.0 breaking changes: Symfony, PHP, API

The breaking changes in the official Sylius 2.0 upgrade guide start with the requirements: PHP 8.2 minimum, Symfony 6.4 or 7.1, and no more Symfony 5.4. Beyond that, the state machine, payment stack, templates and API all change. Here is what each change means in practice, so that a non-specialist can judge the size of the job and a developer can see where to look first.

Symfony and PHP requirements, version by version

The table below compares the composer file of the 1.14 branch, the official upgrade guide and the Sylius 2.3 release notes.

The practical reading is about your server as much as your code. PHP 8.2 gets security fixes until 31 December 2026 and PHP 8.3 until 31 December 2027. A migration done now that settles on PHP 8.2 would already need another step, so I would not choose it as a destination. A shop running on Symfony 5.4 has one more constraint: it must change its framework version as part of the journey, and every bundle it uses has to follow.

The state machine: where business rules hide

The guide changes the default adapter from winzou to Symfony Workflow, and moves the winzou packages to the suggested section of composer.json. For a technical reader, that sentence is clear. For a business reader, the state machine is the set of rules deciding what happens when an order is paid, shipped or cancelled. If someone added a callback that notifies a warehouse when a payment completes, that behaviour lives here. It will not necessarily produce a visible error if it is lost, which makes it the kind of regression to test explicitly.

Payments: Payum and Payment Requests

The guide removes PayPal Express Checkout NVP, Payum Stripe and the Stripe PHP SDK from composer.json, moves Payum routing, and asks for new Messenger transports in the environment file. Sylius presented Payment Requests as experimental in 2.0.0, and no longer experimental in 2.3. This argues for planning the payment work against your real target version. Test authorisation, capture, refund and failed payments with your own provider, in its test environment, and not only the happy path.

Templates and the admin panel

The admin and the shop move to a Bootstrap base with Symfony UX, Sonata block dependencies are removed, and a new Twig Hooks bundle arrives. If you overrode a few templates, this is contained work. If your whole storefront is a custom theme built on Semantic UI and AJAX calls, the migration effort can be dominated by this one section. A plugin named Legacy Shop Bridge restores the older shop for a transition; its listing names versions 2.0 to 2.2.

The API and removed dependencies

API firewalls are renamed, for example from new_api_admin_user to api_admin. The route prefix changes, many legacy routes are removed, and services move under sylius_api. If a mobile app, an ERP or a marketplace connector talks to your shop, list each endpoint it calls before starting. Other removals are quieter: Swiftmailer gives way to symfony/mailer, while packages such as friendsofsymfony/rest-bundle and jms/serializer-bundle disappear from the bundles. Any custom code relying on them has to change.

Later versions add their own changes. Version 2.3 removes ProxyManager and Gaufrette, changes the default of an order lookup setting, adds methods to several interfaces, and fixes a promotion total that was counted twice, which changes cart discount totals shown to customers. That last one is worth flagging to whoever handles your accounts.

How to tell whether this is a big job for you

The list above looks alarming, but it does not all apply to every shop. A nearly standard installation with supported plugins faces configuration work and testing. A shop with custom workflows, a bespoke theme and several integrations faces a real project. Between those two, the only honest measure is a line by line comparison with your own code, and I would be wary of anyone who gives a fixed quote before doing it.

I also have an interest here, since I offer this review as a service. If your shop is close to standard and you have a capable Symfony developer in house, the official guide may be all you need. If you want a plan for the project itself, read my guide to planning a 1.14 migration.

Next step

Compare your composer.json with the table above, then note your PHP version, your Symfony version, your plugins and your integrations. With those four items, a Sylius developer can give you a useful first opinion. You can send them to me through my Sylius developer page; you will speak directly to the person reading the code, and you will get a reply within 24 business hours.