Download the PHP package php-architecture-kit/state-machine without Composer

php-architecture-kit/state-machine

Graph-based state machine engine for PHP. Supports parallel pointers, conditional transitions, typed state, pluggable transition strategies, and task dispatch — all built on top of php-architecture-kit/graph.

Features

• Graph-backed — transitions are directed edges, nodes are vertices
• Parallel pointers — multiple execution cursors moving through the graph simultaneously
• Conditional transitions — guard each edge with a TransitionCondition
• Typed state — key-value State objects attached to each Execution
• Domain events — pointer and state lifecycle emits DomainEvent instances
• Pluggable strategies — swap transition selection and pointer scheduling strategies
• Built-in components — reusable higher-level building blocks for common patterns
• PHP 8.4+ — uses asymmetric visibility and readonly classes

Installation

Quick Start

Core Concepts

StateMachine

Extend StateMachine and register nodes and transitions in the constructor (or any method you choose). Call execute(Execution $execution) to advance all active pointers.

Returns:

• ExecutionStatus::Completed — all pointers finished
• ExecutionStatus::Running — progress was made but pointers remain
• ExecutionStatus::Suspended — no progress, all pointers are blocked

Node

Extend abstract class Node for each step in the workflow. Override handlerClass() to return the FQCN of the NodeHandlerInterface implementation resolved by the PSR-11 container.

Override transitionStrategy() to control how outgoing transitions are selected for that node (defaults to AllValidTransitionsStrategy).

NodeHandlerInterface

NodeHandlerContext provides:

• ExecutionId $executionId
• NodeInterface $node
• Pointer $pointer
• States $states
• dispatchTask(Task $task, array $stamps = []): void

Return NodeHandlerResult::Continue to let the pointer move on, or NodeHandlerResult::Suspended to pause it in place without advancing.

Transition

Directed edge between two NodeIds. Optionally attach a guard condition:

Execution

Holds all Pointers and States for one running instance.

Pointer

Tracks a single cursor position (nodeId). Pointers can be forked for parallel branches. Retrieve events (fork, remove, etc.) via $execution->pointers->getEvents().

State

Named key-value bags attached to an execution.

StateMachineConfig

Controls graph constraints and pluggable strategies:

Built-in Components

Components are reusable, pre-wired sub-graphs. Add them with $machine->addDefinition($component) and connect their ports with addTransition().

AwaitStateComponent

Suspends the pointer until a named state appears in States, with an optional timeout.

SwitchCaseComponent

Routes to the first output whose predicate returns true (XOR gateway).

ParallelComponent

Spawns one pointer per branch (AND-split). Branches can be unconditional or conditionally filtered.

AwaitAllComponent

AND-join: collects all declared branch pointers before continuing.

AsyncComponent

Dispatches a Task exactly once, then suspends until a named state confirms completion. An AwaitStateStamp is automatically added to the task envelope so the handler knows which state key to write back.

The external task handler reads AwaitStateStamp::$stateName from the envelope and calls:

Built-in Transition Strategies

Built-in Pointer Selection Strategies

License

MIT