XState is a state machine library to play with any complex behavior of your PHP objects. It is inspired by xstate.js.

Installation

The recommended way to install Xstate is through Composer.

composer require mouadziani/xstate

Define state machine workflow

Let’s say we want to define a state machine workflow for a video object, generally, a video may have 3 states (playing, stopped, paused),

as a first step, you have to create a new object from StateMachine class

use \Mouadziani\XState\StateMachine;

$video = StateMachine::make();

Then you have to define the allowed states as well as the default state

$video
    ->defaultState('stopped')
    ->states(['playing', 'stopped', 'paused']);

And finally the transitions

use \Mouadziani\XState\Transition;

$video->transitions([
    new Transition('PLAY', ['stopped', 'paused'], 'playing'),
    new Transition('STOP', 'playing', 'stopped'),
    new Transition('PAUSE', 'playing', 'paused'),
    new Transition('RESUME', 'paused', 'playing'),
]);

The Transition class expects 3 required params:

• Trigger: As a name of the transition which will be used to trigger a specific transition (should be unique)
• From: Expect a string for a single / or array for multiple initial allowed states
• To: Expect string which is the next target state (should match one of the defined allowed states)

You can define the whole workflow with a single statement:

$video = StateMachine::make()
    ->defaultState('playing')
    ->states(['playing', 'stopped', 'paused'])
    ->transitions([
        new Transition('PLAY', ['stopped', 'paused'], 'playing'),
        new Transition('STOP', 'playing', 'stopped'),
        new Transition('PAUSE', 'playing', 'paused'),
    ]);

Work with states & transitions

Trigger transition

There are two ways to trigger a specifically defined transition

1- Using transitionTo method and specify the name of the transition as an argument

$video->transitionTo('PLAY');

2- Or just calling the name of the transition from your machine object as a method

$video->play();

Occasionally triggering a transition may throw an exception if the target transition is not defined /or not allowed:

use \Mouadziani\XState\Exceptions;

try {
    $video->transitionTo('RESUME');
} catch (Exceptions\TransitionNotDefinedException $ex) {
    // the target transition is not defined
} catch (Exceptions\TransitionNotAllowedException $ex) {
    // the target transition is not allowed
}

Get the current state

echo $video->currentState(); // playing

Get the allowed transitions

$video->allowedTransitions(); // ['STOP', 'PAUSE']

Adding in-demand transition

$video->addTransition(new Transition('TURN_OFF', 'playing', 'stopped'));

For more details and documentation, you can visit Github.