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, it is worth reviewing 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.
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.
That is why it makes sense to prepare the project for migration first and only then begin the actual upgrade.
The first step should be upgrading to Sylius 1.14, which serves as a natural bridge between the Sylius 1.x line and Sylius 2.
At the same time, it is worth preparing the entire environment:
PHP,
database,
Node.js,
other dependencies used by the project.
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 should be an honest audit of the UI and the extent of project-specific customizations.
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?
Storefront and the Legacy Shop Bridge Plugin
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.
The Admin Panel Requires More Extensive 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.
That is why it is worth taking an honest look at how much custom UI exists 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.
It is worth checking:
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, it is worth limiting the scope of change. Not everything needs to be migrated at the same time.
If the current solution works correctly, a reasonable approach may be to keep Winzou State Machine during the first phase of the migration and postpone the move to Symfony Workflow until later.
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.
However, it is worth protecting the most important 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.
Do Not Forget Manual Testing!
After the migration, it is worth going through the most important scenarios manually to make sure that everything works and looks as expected.
Choose the Right Time
It is not a good idea to 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.
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, it is worth preparing 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.
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.
It is also worth asking 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.
Our educational hub includes:
an upgrade readiness checklist,
the Plugin Compatibility Radar,
technical resources on Sylius 2 migration.
Yes. It is the natural bridge between the Sylius 1.x and 2.x lines.
It can help reduce the scope of changes, but compatibility with other extensions needs to be verified.
No. In many cases, it makes sense to limit the scope of the first migration phase.
Yes, but the risk of regression increases significantly.
Most commonly, from approximately two to six weeks or longer, depending on the complexity of the project.
One of the first questions companies ask when planning a Sylius-based e-commerce platform is simple: how much will the i...
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 →
Managing currencies and multi-jurisdictional taxes is foundational to any enterprise e-commerce platform. This guide dec...
Read more →
