Deciding to migrate to Sylius 2 is only the beginning. In practice, the success of the upgrade depends much more on preparation than on the update process itself.
The fewer things you change at the same time, the greater the chance of completing the migration safely. That is why, before starting the work, review several areas that most often affect the cost, scope and risk of the entire project.
Planning an upgrade to Sylius 2? We have created an educational hub for technical teams responsible for migration. It includes an upgrade readiness checklist, the Plugin Compatibility Radar and resources that help estimate the scope of work and technical risks.
This checklist assumes the decision to migrate has already been made. If it has not, start by checking whether the upgrade pays off in your project. One of the most important principles when migrating to Sylius 2 is to limit the surface area of change.
If you update the environment, rebuild the frontend, change the state machine, upgrade plugins and modify the API at the same time, the risk of regression and the overall project cost increase very quickly.
So prepare the project first and only then begin the actual upgrade. The same order applies to any larger technical project – clarity before code.
Start with Sylius 1.14. It is the bridge release between the Sylius 1.x line and Sylius 2. If you are new to the platform, start with our guide to Sylius.
At the same time, prepare the entire environment:
PHP,
database,
Node.js,
other dependencies used by the project.
Sylius 2 requires PHP 8.2 or newer and Symfony 6.4 or 7.2 – check where your project stands before you start.
The goal is to minimize the number of moving parts during the migration itself. The more changes you can complete beforehand, the easier the actual upgrade will be.
The second step is an honest audit of the UI and the scope of customizations in your project.
This is a good time to answer a few questions:
How many changes have been introduced over the years?
Which elements are still necessary?
Which features can be postponed or even removed?
If the store has a heavily customized storefront, the Legacy Shop Bridge Plugin can help reduce the scope of the first migration phase.
However, compatibility with other plugins and extensions always needs to be verified individually. You should not assume that the entire ecosystem will work without additional changes.
There is no simple transitional path for the administration panel. Migration means moving from Semantic UI and jQuery to Bootstrap, Vanilla JS and, where needed, Stimulus controllers.
Count how much custom UI sits in the administration panel in the administration panel, which features are still being used and whether every customization continues to have a valid business justification.
Some functionality can be postponed to later stages or removed entirely.
The Sylius ecosystem has done a tremendous amount of work recently.
The most popular extensions have already been adapted to Sylius 2. This applies both to official plugins and to many solutions developed by the community.
However, the availability of a Sylius 2-compatible version does not automatically mean full compatibility with your project.
Check:
whether the plugins you use support Sylius 2,
what changes were introduced between versions,
whether the migration requires changes to your custom code.
Some plugin changes may be just as significant as the framework upgrade itself.
Our educational Sylius 2 migration hub includes the Plugin Compatibility Radar, a tool that helps assess the readiness of the most popular extensions.
If your project uses custom state machine extensions, limit the scope of change. Not everything needs to be migrated at the same time.
If the current solution works correctly, keep Winzou State Machine during the first phase of the migration and postpone the move to Symfony Workflow until later. We recorded a separate piece on migrating Winzou State Machine.
The key principle remains the same: the fewer areas you change at the same time, the greater the chance of a safe upgrade.
If your store does not have automated tests, the Sylius 2 upgrade is a good opportunity to change that, at least to some extent.
You do not need to achieve full test coverage immediately.
Protect the most business-critical paths:
purchasing process,
checkout,
payments,
user registration,
key integrations.
The greatest value of testing is reducing the risk of regression. Without tests, it is difficult to be confident that the most important processes still work correctly after the migration.
After the migration, go through the most important scenarios manually to make sure that everything works and looks as expected.
Do not schedule the migration immediately before a peak sales season.
It is much safer to carry it out when the business has more room to deal with potential issues and fixes – and when the team is prepared for it.
If the project uses API Platform, the migration also involves a major version jump. In this case, contract testing becomes particularly important.
Its purpose is to ensure that the frontend continues to receive exactly the data it expects.
Before the migration, prepare a set of simple tests that verify the structure of API responses. Once the upgrade is complete, you can check whether any fields have been lost or changed.
For headless projects, this is one of the most important safeguards in the entire migration process. You can see how it plays out on a live project in our headless Sylius migration case study.
There is no single universal answer.
Based on experience, however, a migration can take from approximately two weeks to six weeks or longer.
The project timeline is influenced by factors including:
the scope of UI customizations,
the number of plugins,
the use of API Platform,
the complexity of the state machine,
the number of integrations,
the level of test coverage.
The same factors drive the cost of a Sylius implementation – time and budget scale together here. Ask whether all existing features and plugins are still necessary.
Sometimes removing unused elements is the cheapest and fastest way to reduce the cost of migration.
After all, code that does not exist cannot generate errors.
If you are planning a migration to Sylius 2, we have prepared a set of resources designed to help reduce the risk and cost of the entire process. And if you would rather hand the whole thing over, we also deliver e-commerce implementations and migrations end-to-end.
Our educational hub includes:
an upgrade readiness checklist,
the Plugin Compatibility Radar,
technical resources on Sylius 2 migration.
Yes. Sylius 1.14 is the bridge release – it collects the deprecations pointing toward the 2.x line, so you can split the migration into two smaller steps instead of one large jump. Going straight from an earlier 1.x version to 2.0 means every problem surfaces at once, and it is hard to tell which change caused what.
Partly. It lets you postpone rewriting the storefront and close the first phase faster, but it does not remove the need to verify every other extension individually. It does not cover the administration panel at all, so if that is where your customizations live, the bridge saves you nothing.
No. If your current state machine extensions work correctly, keep Winzou for the first phase and treat the move to Symfony Workflow as a separate project. The same principle applies across the whole migration: the fewer areas you touch at once, the easier it is to identify what broke.
Yes, but then manual clicking after deployment is your only safety net. You do not need full coverage – the purchase path, checkout, payments, registration and key integrations are enough. Without them you have no way of knowing whether orders still go through until a customer reports it.
Six things: the scope of UI customizations, the number of plugins, the use of API Platform, the complexity of the state machine, the number of integrations and the level of test coverage. Admin panel customization usually carries the most weight – it is what decides whether the project closes in two weeks or six.
Choosing a framework may seem like a purely technical decision. In practice, however, it affects much more than how deve...
Read more →
AI is becoming an increasingly important part of the day-to-day work of e-commerce development teams. It helps generate ...
Read more →
Upgrading from Sylius 1 to Sylius 2 can be the right decision, but it will not be the best direction for every project. ...
Read more →
