mouadziani / xstate
State machine library to play with any complex behavior of your PHP objects
Fund package maintenance!
mouadziani
Installs: 5 061
Dependents: 0
Suggesters: 0
Security: 0
Stars: 85
Watchers: 2
Forks: 5
Open Issues: 1
Requires
- php: ^8.0
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.0
- pestphp/pest: ^1.20
This package is auto-updated.
Last update: 2025-03-08 23:09:16 UTC
README
XState - State Machine for PHP
XState is a state machine library to play with any complex behavior of your PHP objects (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 expect 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)
Guards (optional)
You can either define a guard callback for a specific transition using guard
method, which must return a bool. If a guard returns false, the transition cannot be performed.
use \Mouadziani\XState\Transition; $video->transitions([ (new Transition('PLAY', ['stopped', 'paused'], 'playing')) ->guard(function ($from, $to) { return true; }) ]);
💡 You can define the whole workflow using 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 specific 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'));
Upcoming features
- Add the ability to define guard for a specific transition
- Define/handle hooks before/after triggering transition
Testing
composer test
Security Vulnerabilities
Please review our security policy on how to report security vulnerabilities.
Credits
License
The MIT License (MIT). Please see License File for more information.
featured_repository