Welcome to our blog, where we share news related to Sylius and post about technology & eCommerce.

Mateusz Zalewski
22.08.2019 | 3 mins read

What is State Machine and why is it useful in modeling eCommerce processes

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!

PRE-SALE €490 €389
until September 30
Getting started with Sylius
Online course (8h)

Mateusz Zalewski
See my roles

Being a programmer is not only his job - it is the way of his life. Strong BDD believer and testing enthusiast. Curious about world and passionate about science. Privately a member of medieval reenactment group, a fervent traveller and FC Barcelona fan. Loves discovering new places, meeting interesting people and developing himself to be a better programmer and a better human being.

Be the first to find out about new posts. Join to our newsletter!