Download the PHP package smskin/laravel-saga without Composer

State Machine Engine for Laravel Projects

While working with .Net Core and MassTransit, it became frustrating that Laravel lacked a ready-made state machine engine. Inspired by MassTransit, I wrote a library that functions similarly to MassTransit sagas.

Installation

Configuration

In the configuration file , you will find the engine settings and descriptions of state machines.

• logger - a class responsible for logging the state machine's operation process. Can be changed to another class implementing the interface.
• state-machines - an array of registered state machines.
• repositories
  • default - the repository for storing the state machine's state (database).
  • database
  • class - the repository class. Can be changed to another class implementing the interface.
  • table - the name of the table where the state machine's state will be stored.

Saga Structure

Let's examine a saga from an example in this library ().

Property $context

This property describes the type (cast) of the stored object of the state machine. It can be any class inheriting from SagaContext. This object allows storing intermediate values obtained during interaction with other services during operation.

Method setup()

This method describes the state machine's operation algorithm.

Three key blocks of a saga:

• correlation
• initialization event\command
• state machine transition logic

Correlation

This block describes the algorithm for obtaining the identifier of the state machine's context in the repository. It's described using two methods:

• correlatedById - getting the object by ID.
• correlatedBy - getting it by any storage field.

This block can be read as: Upon receiving the EUserCreated event, take the state machine's ID from the property.

This block can be read as: Upon receiving the EUserBlocked event, find the state machine by the field, taking the value from the event. Thus, the engine can search for the state machine's context both by UUID and by any context field.

Initialization Event\Command

This block describes the events\commands that will initialize the state machine.

The method takes two arguments:

• The event class to be registered in Laravel.
• A Closure for transforming the event into the state machine's context. With this method, you can save some initialization data in the context object.

This block can be read as:

• Upon receiving the CreateUserCommand command, initialize the state machine.
• Take the state machine's ID from the command.
• Save the from the command in the state machine's context.

State Machine Transition Logic

This block describes the state machine's algorithm. Key phrases:

• • while in the state machine's state.
• • upon receiving an event.
• • do (closure).
• • perform a subroutine (class implementing the IActivity interface).
• • switch the state machine's status.
• • publish an event.
• • sugar for initialization (first stage).
• • sugar for finalization.

This block can be read as:

• Upon initialization.
• Switch the state to .
• Perform the subprogram.
• Execute the Closure - call , passing the and (which we stored in the context during initialization).

This block can be read as:

• While in the state .
• Upon receiving the event.
• Execute the Closure, which will write the (from the event) into the state machine's context.
• Switch the state to .
• Execute the Closure - call , passing the from the context.

This block can be read as:

• While in the state .
• Upon receiving the event.
• Finalize the state machine.
• Publish the event , passing the .

Basic Operation Principle

The engine operates based on the Laravel Events. The events described in the method are registered in the EventServiceProvider. The saga acts as a Listener.

When an event enters the bus, the Laravel broker executes the method of the sagas registered for that event.

Execution Optimization

Since the events to which the saga registers are described within the saga itself, Laravel will require time to compute these events from all sagas. To optimize this, an artisan command is written that saves a pre-computed cache of event=saga mapping ready for registration.

Caching

Cache Clearing

Configuration Options

Changing the Saga Data Storage Repository

1. Create a class implementing the interface.
2. Add it to the configuration.
3. Specify it in the configuration variable.

Changing the Logger

1. Create a class implementing the interface.
2. Specify it in the configuration.

Creating Custom Sagas

1. Create a class inheriting from .
2. Describe the logic of the state machine in the method.
3. Specify the class in the configuration.