finite PHP Finite State Machine

To make an object stateful, it must have a property to hold the current state and corresponding getter/setter methods. The state property should be typed with your state Enum.

class Document
{
    private DocumentState $state = DocumentState::DRAFT;

    public function getState(): DocumentState
    {
        return $this->state;
    }

    public function setState(DocumentState $state): void
    {
        $this->state = $state;
    }
}

Install the Finite state machine library using Composer:

 $ composer req yohang/finite

Instead of using metadata properties, Finite 2.0 encourages adding logic directly to your State Enum. Since states are Enums, you can define methods that return boolean values or other data based on the current state. This allows you to check business rules (like isDeletable()) directly on the state object without needing the StateMachine instance.

enum DocumentState: string implements State
{
    // ...

    public function isDeletable(): bool
    {
        return in_array($this, [self::DRAFT, self::DISABLED]);
    }

    public function isPrintable(): bool
    {
        return in_array($this, [self::PUBLISHED, self::REPORTED]);
    }
}

// Usage:
var_dump($document->getState()->isDeletable());

To use Finite in a Symfony project, register the Finite\Extension\Symfony\Bundle\FiniteBundle in your config/bundles.php file. This provides the StateMachine service and Twig extensions automatically.

return [
    // ...
    Finite\Extension\Symfony\Bundle\FiniteBundle::class => ['all' => true],
];

The StateMachine acts as the orchestrator for state changes. The lifecycle of a transition follows this sequence:

1. Validation: can() checks if the transition is valid for the current state and if any CanTransitionEvent listeners block it.
2. Pre-Transition: apply() dispatches a PreTransitionEvent.
3. Processing: The transition's process() method is called to execute custom business logic.
4. State Update: The object's state property is updated to the transition's target state.
5. Post-Transition: A PostTransitionEvent is dispatched.

This lifecycle ensures that business logic and side effects can be hooked into at every critical stage.

Initialize a Finite\StateMachine and pass your stateful object to its methods. Use can($object, 'transition_name') to check if a transition is valid for the current state, and apply($object, 'transition_name') to execute the transition and update the object's state.

use Finite\StateMachine;

$document = new Document;
$sm = new StateMachine;

// Can we process a transition ?
$sm->can($document, 'publish');

// Apply a transition
$sm->apply($document, 'publish'); 

Once the Symfony bundle is installed, you can use these Twig helpers:

• finite_can(object, 'transition_name'): Returns true if the transition is available for the object.
• finite_reachable_transitions(object): Returns a list of all reachable transitions for the object.

{# Check if a transition is available #}
{% if finite_can(document, 'publish') %}
    <a href="...">Publish</a>
{% endif %}

{# List all reachable transitions #}
<ul>
    {% for transition in finite_reachable_transitions(document) %}
        <li>{{ transition.name }}</li>
    {% endfor %}
</ul>

You can dump your state machine graph in Mermaid format using the Symfony console command. Replace App\State\DocumentState with your actual state Enum class name.

php bin/console finite:state-machine:dump "App\State\DocumentState" mermaid

The StateMachine constructor accepts two optional dependencies:

1. EventDispatcherInterface $dispatcher: An implementation of the PSR-14 event dispatcher. Defaults to a new Finite\Event\EventDispatcher.
2. StatePropertyExtractor $statePropertyExtractor: An extractor used to locate the state property on the target object. Defaults to MemoizedStatePropertyExtractor.

use Finite\StateMachine;
use Finite\Event\EventDispatcher;

$stateMachine = new StateMachine(new EventDispatcher());