PHP Classes

PHP State Machine Implementation: Define a state machine and process trigger events

Recommend this page to a friend!
  Info   View files Documentation   Screenshots Screenshots   View files View files (15)   DownloadInstall with Composer Download .zip   Reputation   Support forum   Blog    
Last Updated Ratings Unique User Downloads Download Rankings
2022-10-14 (3 months ago) RSS 2.0 feedNot yet rated by the usersTotal: 41 All time: 10,532 This week: 349Up
Version License PHP version Categories
php-state-machine 1.0GNU General Publi...5PHP 5, Data types
Description Author

This package can define a state machine and process trigger events.

It has a class that can take the definition of the machine states and the transitions between the different states.

The package can also process the events that may be triggered and update the states of the machine according to the machine's definition.

Picture of Javier Garrido
Name: Javier Garrido <contact>
Classes: 1 package by
Country: Spain Spain

Details

<h1 align="center">PHP State Machine</h1>

<p align="center">

<img src="https://github.com/jagarsoft/php-state-machine/raw/master/assets/images/StateMachine-Logo.png" alt="StateMachine Logo" width="150" height="150">

</p>

<p align="center">

<a href="https://scrutinizer-ci.com/g/jagarsoft/php-state-machine/?branch=master"><img src="https://scrutinizer-ci.com/g/jagarsoft/php-state-machine/badges/quality-score.png?b=master" alt="Scrutinizer Code Quality"></a>
<a href="https://scrutinizer-ci.com/g/jagarsoft/php-state-machine/?branch=master"><img src="https://scrutinizer-ci.com/g/jagarsoft/php-state-machine/badges/coverage.png?b=master" alt="Code Coverage"></a>
<a href="https://scrutinizer-ci.com/g/jagarsoft/php-state-machine/build-status/master"><img src="https://scrutinizer-ci.com/g/jagarsoft/php-state-machine/badges/build.png?b=master" alt="Build Status"></a>
<a href="https://packagist.org/packages/jagarsoft/php-state-machine"><img src="https://img.shields.io/packagist/dt/jagarsoft/php-state-machine?style=plastic" alt="Packagist Downloads"></a>
<a href="https://www.php.net/"><img src="https://img.shields.io/badge/language-PHP-green.svg?longCache=true&style=plastic" alt="language PHP"></a>
<a href="http://perso.crans.org/besson/LICENSE.html"><img src="https://img.shields.io/badge/License-GPL-blue.svg?longCache=true&style=plastic" alt="GPL license"></a>
<a href="https://shields.io"><img src="https://img.shields.io/badge/badges-shields.io-green.svg?longCache=true&style=plastic" alt="Badges shields.io"></a>

</p>

What is a State Machine?

It's a data structure made of two key items: * States * Transitions

Transitions go from an initial state to a destination state fired by events.

You can view a State Machine as a graph like this [^1]:

State diagram for a turnstile

Also, you can think about it, as a double-entry array or _State Transition Table_ indexed by current state and current event. Content will be the next state [^1]:

state-transition-table

Bound to the next state, you can set a action function that will be executed when event will be raised at the current state, after run, the new state will be set. In foremention example, output may be the action performed by bound function over some servomotor or something like that (save data, etc).

You can cancel the transition to the next state invoking _cancelTransition_ within action function. Current state will be remain.

Action functions are atomic. If you fire new events in an action function, they will be enqueued, and their action functions, if any, will be invoked consecutively, every time action function return.

If you cancel transition within a nested event, subsequent events may fail if no alternative event is defined for the current state.

Unexpected events for the current state will throw an exception.

You can fire common event from any state, by defining a _addCommonTransition_ with expected event and destination state only, but you must add all states yet.

[^1]: https://en.wikipedia.org/wiki/Finite-state_machine

Installing

By _Composer_, just issue next command:

composer require jagarsoft/php-state-machine

Getting started

$state_1 = StateEnum::STATE_1;
$state_2 = StateEnum::STATE_2;
$state_3 = StateEnum::STATE_3;

$event_a = EventEnum::EVENT_A;
$event_b = EventEnum::EVENT_B;
$event_c = EventEnum::EVENT_C;

echo PHP_EOL;
$commonAction = function (StateMachine $sm){
    echo "My current state is {$sm->getCurrentState()}".
         " on {$sm->getCurrentEvent()}".
         " and {$sm->getNextState()} will be the next state".PHP_EOL;
};

(new StateMachine())
        ->addState($state_1)
        ->addState($state_2)
        ->addState($state_3)

        ->addTransition($state_1, $event_a, $state_2, $commonAction)
        ->addTransition($state_2, $event_b, $state_3, $commonAction)
        ->addTransition($state_3, $event_c, $state_1, $commonAction)

        ->fireEvent($event_a)
        ->fireEvent($event_b)
        ->fireEvent($event_c)

        ->fireEvent($event_a)
        ->fireEvent($event_b)
        ->fireEvent($event_c);

Output:

My current state is 1 on A and 2 will be the next state
My current state is 2 on B and 3 will be the next state
My current state is 3 on C and 1 will be the next state
My current state is 1 on A and 2 will be the next state
My current state is 2 on B and 3 will be the next state
My current state is 3 on C and 1 will be the next state

Features

_StateMachine_ gives you the followings features:

  1. You can prove a _event_ before it be fired
  2. You can execute a _guard_ in order to cancel transition
  3. You can execute a function _before_ and/or _after_ action
  4. You can create _StateMachine_ from _Array_ or _Winzou_ config
  5. You can store extra data in transition

Coming soon... you will be able to create _StateMachine_ from other sources, for instance, DOT definition. _StateMachine_ so created is fully functional and will respond to their events. Moveover, you will be able to save your current _StateMachine_ to that format too.

Licence

GNU General Public License v2.0 only

Screenshots  
  • state-transition-table.png
  Files folder image Files  
File Role Description
Files folder imageassets (1 directory)
Files folder imagesrc (3 files)
Files folder imagetests (1 file, 1 directory)
Accessible without login Plain text file .scrutinizer.yml Data Auxiliary data
Accessible without login Plain text file composer.json Data Auxiliary data
Accessible without login Plain text file composer.lock Data Auxiliary data
Accessible without login Plain text file LICENSE Lic. License text
Accessible without login Plain text file phpunit.xml Data Auxiliary data
Accessible without login Plain text file README.md Doc. Documentation

  Files folder image Files  /  assets  
File Role Description
Files folder imageimages (1 file)

  Files folder image Files  /  assets  /  images  
File Role Description
  Accessible without login Image file StateMachine-Logo.png Icon Icon image

  Files folder image Files  /  src  
File Role Description
  Plain text file ActionsKeyEnum.php Class Class source
  Plain text file StateMachine.php Class Class source
  Plain text file StateMachineBuilder.php Class Class source

  Files folder image Files  /  tests  
File Role Description
Files folder imageStubs (4 files)
  Plain text file StateMachineTest.php Class Class source

  Files folder image Files  /  tests  /  Stubs  
File Role Description
  Plain text file EventEnum.php Class Class source
  Plain text file StateEnum.php Class Class source
  Plain text file StateMachineArrayBuilder.php Class Class source
  Plain text file StateMachineWinzouBuilder.php Class Class source

 Version Control Unique User Downloads Download Rankings  
 100%
Total:41
This week:0
All time:10,532
This week:349Up