README

Finite State Machine implementation in PHP

Installation

Install via composer

Add dependency to your composer.json file and run composer update.

"szykra/state-machine": "~0.1.0"

or just run

composer require szykra/state-machine

Usage

Prepare your entity to be stateful

Your entity should implements interface StatefulInterface. It requires two new methods

public function getState();
public function setState($state);

Of course you should add new property named e.g. state.

Configure a StateMachine by adding States and Transitions

To control your entity by StateMachine you have to define:

States
Transitions between States

State

State object simply represents a state. It has name and list of available transitions.

$stateDraft = new State('draft');
$statePublished = new State('published');

Transition

Transition is like single action which someone performs on an object. It means transition from one state to another state.

$stateDraft->addTransition('publish', 'draft', 'published');

$transitionReject = new Transition('reject', 'published', 'rejected');
$statePublished->putTransition($transitionReject);

Each state has own transitions so available transitions depend on the current state of object.

StateMachine

StateMachine is a controller used to change state of stateful object. First you should create a StateMachine object and set up it by adding a valid States.

$stateMachine = new StateMachine();

// api inconsistent, should called putState
$stateMachine->addState($stateDraft);
$stateMachine->addState($statePublished);

Initialize a State Machine

When your StateMachine is ready you could initialize it by Stateful Object.

$document = new Document();
$stateMachine->initialize($document);

Now you could change state of $document by $stateMachine. To check if transition can be performed use the can($transition) method, e.g. if current state of $document is draft the results will be as follows

$stateMachine->can('publish'); // true
$stateMachine->can('reject'); // false

To change state of object you should use run($transition) method. If transition not exists TransitionNotFoundException will be thrown.

echo $document->getState();    // draft
$stateMachine->run('publish');
echo $document->getState();    // published

If you want to see a complete example please see tests/ directory.

To do

Ability to setup callbacks before/after change states
List all states
List all transitions
Add configurable loader to StateMachine
Add configurable conditionals to transitions

szykra / state-machine

Maintainers

Details