3 min. read
Categories: Technical
What is State Machine and why is it useful in modeling eCommerce processes
In Sylius, a state machine is a widely used concept. If you’ve ever read some Sylius’ code, you have probably seen it, even if you were not aware of it.

Hello folks! I would like to write a little about one of the essential concepts in Sylius. If you know what it is, you’re probably aware of why it’s so cool. If you don’t, there is no better time to learn it!

Base Concept

The concept itself is neither new nor especially complicated. The state machine (in mathematics usually called finite state machine), is a model that describes the sequential logic of some process. It can be implemented both in software and hardware and represented as a simple graph


Of course, there are multiple variations of this concept, but the main idea is always the same – a bunch of states between which we can move with strictly specified transitions.

PHP Libraries

In Sylius, a state machine is a widely used concept. If you’ve ever read some Sylius’ code, you have probably seen it, even if you were not aware of it. Many business processes are modeled with such an approach, starting from the checkout process, ending with the order’s shipment management.

To reach this goal, we use a fabulous WinzouStateMachineBundle, which is an integration layer between Symfony and state machine library, from the same vendor. It’s, of course, not the only library that provides state machine mechanisms for the PHP application (you can check out Symfony/Workflow or Finite).

WinzouStateMachineBundle allows us to use simple YAML configurations, to define even the most complicated processes:

        class: "%sylius.model.order.class%"
        property_path: checkoutState
        graph: sylius_order_checkout
        state_machine_class: "%sylius.state_machine.class%"
            cart: ~
            addressed: ~
            shipping_selected: ~
            shipping_skipped: ~
            payment_skipped: ~
            payment_selected: ~
            completed: ~
                from: [cart, addressed, shipping_selected, shipping_skipped, payment_selected, payment_skipped]
                to: addressed
                from: [addressed]
                to: shipping_skipped
                from: [addressed, shipping_selected, payment_selected, payment_skipped]
                to: shipping_selected
                from: [shipping_selected, shipping_skipped]
                to: payment_skipped
                from: [payment_selected, shipping_skipped, shipping_selected]
                to: payment_selected
                from: [payment_selected, payment_skipped]
                to: completed

What is more, it’s also possible to react to the state’s changes, with so-called callbacks. These are Symfony services, which can operate on a transitioned entity and reflect its change in other parts of the application (like sending an email after shipping the shipment).

In fact, we like this concept so much that there is even a unique applyStateMachineTransition action in our basic controller for resources.

Benefits for eCommerce Projects

What are the benefits of implementing the State Machine concept in an eCommerce application? Here are some of the key arguments in favor of state machine:

  • It gives you a standard way to configure and execute business processes, like checkout, shipping and many more found in eCommerce projects;
  • It helps you prevent invalid workflows. Most of the legacy platforms change the states by setting new data on the entity, while the state machine library in Sylius will check if you CAN make a transition;
  • It provides you with an elegant extension point for existing processes with new actions, for example: Want to notify the external system or send an email when order is paid or confirmed? Add a new callback. You do not like the way Sylius reserves inventory in the checkout? Customize the configuration and move the callback to a different transition.


Of course, there are some disadvantages as well. Even though YAML configuration is quite easy to read, it’s also hard to maintain (which is the reason why so many developers are not fond of this format). Most of the libraries also require a public setState method, which does not prevent us from unneeded states changes (when the state machine is used, states should always be changed with transitions instead of setters!).


As always, it’s just a pick of an iceberg. Like in any other case, the best way to learn a thing is by writing down a few lines of code 🙂 Also, if you find this topic interesting, you can study Sylius’ source a little bit, to become more familiar with the concept.

Enjoyed this post? If you need more information and guidance, we have launched a pre-sale of our first official online video course. For sure, the state machine usage will be an important part of it. Hope to see you soon!

Mateusz Zalewski
Long-time Core Team member and the main Trainer in the Sylius company with the current focus on improving training programs to make them as fun and developing for the Sylius newcomers as possible. He's also hung up on enhancing Sylius' architecture and its plugins' system. Privately, a huge enthusiast of history and astronomy.
More from our blog
Business News Technical 3 min read 28.09.2020
Get ready for global sales & operations with the most advanced payment solution from the famous fintech giant, now available in Sylius out of the box. Read More
Business News 3 min read 14.09.2020
We proudly present to you the latest version of the Sylius eCommerce Platform – 1.8, which comes with a brand new, unified API powered by API Platform, Loyalty points system for Sylius Plus, and as you can probably see, a brand new sylius.com website! Numbers This new release is a… Read More
Business Ecosystem News 3 min read 13.08.2020
Read why the French market leader trusted Sylius in a strategic re-platforming process to get a competitive eCommerce advantage. Read More