StateMachine
Reference for the StateMachine module: declare a state machine with its states and transitions, then run a named transition against an entity. A transition locks the entity row, checks the current state is allowed, appends a new row to the status log, updates the entity's current status, and runs an optional callback, all in one transaction.
This page is a pure reference. Configure a machine with StateMachineConfig, then call StateMachine::Transition to move an entity between states.
StateMachine- run a named state transition atomically.StateMachineConfig- register machines, states and transitions, and read them back.StateMachineStatusDatabase- insert a row into a status log table.StateMachineInvalidStateException- thrown when a state is invalid.StateMachineInvalidTransitionException- thrown when a transition is invalid.
StateMachine
The transition execution engine. Runs a configured transition inside a database transaction that locks the entity row, validates the current state, appends to the status log, updates the denormalised current status, and runs the transition callback.
Transition
StateMachine::Transition(string $machine, int $entityId, string $transitionName, array $optionalParameters = []): bool
Execute a state transition atomically. Locks the entity row, validates that the current state is one of the transition's from states, inserts a new status log row, updates the entity's current status, and runs the transition callback within the transaction. If the callback throws, the transaction rolls back and false is returned.
| Name | Type | Description |
|---|---|---|
$machine | string | Machine identifier. |
$entityId | int | Entity ID to transition. |
$transitionName | string | Transition name. |
$optionalParameters | array | Additional parameters passed to the callback. |
Returns bool True if the transition succeeded, false if it failed.
StateMachineConfig
Configuration management for state machines. Registers machines, their states and their transitions, reads that configuration back, checks whether a transition is currently allowed, and registers callbacks that run after a status row is inserted.
AddState
StateMachineConfig::AddState(string $machine, string $name, int $value, bool $isInitial = false): void
Register a state on a machine. Throws if the machine is not registered, or if the state name or value already exists on the machine.
| Name | Type | Description |
|---|---|---|
$machine | string | Machine identifier. |
$name | string | State name. |
$value | int | State integer value. |
$isInitial | bool | Whether this is the initial state. |
Returns void
AddStateMachine
StateMachineConfig::AddStateMachine(string $name, string $entityTable, string $entityIdColumn, string $statusTable, string $statusColumn, string $currentStatusColumn): void
Register a state machine. Throws if a machine with the same name is already registered.
| Name | Type | Description |
|---|---|---|
$name | string | Machine identifier. |
$entityTable | string | Entity table name. |
$entityIdColumn | string | Entity ID column. |
$statusTable | string | Status log table name. |
$statusColumn | string | Status column in the log table. |
$currentStatusColumn | string | Denormalised current status column on the entity. |
Returns void
AddTransition
StateMachineConfig::AddTransition(string $machine, string $name, string|array $from, string $to, ?callable $transitionCallback = null): void
Register a transition on a machine. Validates that the from and to states exist, and throws if the machine is not registered or the transition name already exists.
| Name | Type | Description |
|---|---|---|
$machine | string | Machine identifier. |
$name | string | Transition name. |
$from | string|array | Source state or states; can be an array for multiple. |
$to | string | Destination state. |
$transitionCallback | ?callable | Module-specific callback executed within the transaction. |
Returns void
CanTransition
StateMachineConfig::CanTransition(string $machine, int $entityId, string $transitionName): bool
Check whether a transition is allowed from the entity's current state. Reads the entity's current status and compares it against the transition's from states. Returns false if any lookup fails.
| Name | Type | Description |
|---|---|---|
$machine | string | Machine identifier. |
$entityId | int | Entity ID. |
$transitionName | string | Transition name. |
Returns bool True if the transition is allowed, false otherwise.
GetAfterStatusInsertCallbacks
StateMachineConfig::GetAfterStatusInsertCallbacks(string $statusTable): array
The callbacks registered to run after a status row is inserted for the given status table.
| Name | Type | Description |
|---|---|---|
$statusTable | string | Status log table name. |
Returns array A list of callables, each receiving the entity ID.
GetMachine
StateMachineConfig::GetMachine(string $machine): array
The configuration for a registered machine. Throws if the machine is not registered.
| Name | Type | Description |
|---|---|---|
$machine | string | Machine identifier. |
Returns array Machine configuration.
GetStateValue
StateMachineConfig::GetStateValue(string $machine, string $stateName): int
The integer value of a state by name. Throws StateMachineInvalidStateException if the state does not exist on the machine.
| Name | Type | Description |
|---|---|---|
$machine | string | Machine identifier. |
$stateName | string | State name. |
Returns int State value.
GetTransition
StateMachineConfig::GetTransition(string $machine, string $transitionName): array
The configuration for a registered transition. Throws if the machine has no transitions registered, or the named transition does not exist.
| Name | Type | Description |
|---|---|---|
$machine | string | Machine identifier. |
$transitionName | string | Transition name. |
Returns array Transition configuration.
RegisterAfterStatusInsert
StateMachineConfig::RegisterAfterStatusInsert(string $statusTable, callable $callback): void
Register a callback invoked after a status log row is inserted for the given status table. The callback receives the entity ID.
| Name | Type | Description |
|---|---|---|
$statusTable | string | Status log table name. |
$callback | callable | Callback receiving the entity ID. |
Returns void
StateMachineStatusDatabase
Database operations for status log entries. Inserts an append-only row into a status log table and runs any registered after-insert callbacks.
Insert
StateMachineStatusDatabase::Insert(string $statusTable, int $entityId, int $status, string $statusColumn): int
Insert a new status log entry, then run any callbacks registered for the status table. Derives the entity ID column and created-timestamp column from the status table name.
| Name | Type | Description |
|---|---|---|
$statusTable | string | Status log table name. |
$entityId | int | Entity ID. |
$status | int | Status value. |
$statusColumn | string | Status column name in the log table. |
Returns int Inserted row ID.
StateMachineInvalidStateException
Thrown when a state is invalid, for example when a transition references a state that does not exist on the machine, or a state value is looked up by an unknown name. Extends the built-in Exception.
StateMachineInvalidTransitionException
Thrown when a transition is invalid, for example when the entity's current state is not one of the transition's from states. Extends the built-in Exception.