StateMachineHandler
in package
Handles configurable state machine transitions with dual status/state tracking, field rules, and audit logging. Designed for use by the workflow engine's stateMachine node type but generic enough for any entity with state tracking.
Table of Contents
Methods
- applySetRules() : array<string|int, mixed>
- Apply "Set" rules to entity data, auto-populating fields for the target state.
- createAuditLog() : void
- Create an audit log entry for a state transition.
- executeTransition() : array{success: bool, entityData?: array, newStatus?: string, error?: string, missingFields?: array}
- Execute a full state transition: validate, apply rules, resolve status.
- resolveStatus() : string|null
- Determine the status category that contains the given state.
- validateRequiredFields() : array<string|int, mixed>
- Validate that all required fields for a state transition are present and non-empty.
- validateTransition() : bool
- Check whether a transition from one state to another is allowed.
Methods
applySetRules()
Apply "Set" rules to entity data, auto-populating fields for the target state.
public
applySetRules(array<string|int, mixed> $entityData, array<string|int, mixed> $rules) : array<string|int, mixed>
Parameters
- $entityData : array<string|int, mixed>
-
The current entity data (key-value pairs).
- $rules : array<string|int, mixed>
-
The state rules containing optional 'set' key.
Return values
array<string|int, mixed> —The modified entity data.
createAuditLog()
Create an audit log entry for a state transition.
public
createAuditLog(array<string|int, mixed> $auditConfig, string $fromState, string $toState, string $fromStatus, string $toStatus, int $entityId[, int|null $userId = null ]) : void
Parameters
- $auditConfig : array<string|int, mixed>
-
The audit log configuration with 'table' and 'fields' keys.
- $fromState : string
-
Previous state.
- $toState : string
-
New state.
- $fromStatus : string
-
Previous status category.
- $toStatus : string
-
New status category.
- $entityId : int
-
The entity being transitioned.
- $userId : int|null = null
-
The user performing the transition.
executeTransition()
Execute a full state transition: validate, apply rules, resolve status.
public
executeTransition(array<string|int, mixed> $entityData, string $currentState, string $targetState, array<string|int, mixed> $config) : array{success: bool, entityData?: array, newStatus?: string, error?: string, missingFields?: array}
Parameters
- $entityData : array<string|int, mixed>
-
Current entity data.
- $currentState : string
-
The current state value.
- $targetState : string
-
The requested target state.
- $config : array<string|int, mixed>
-
Full state machine configuration.
Return values
array{success: bool, entityData?: array, newStatus?: string, error?: string, missingFields?: array}resolveStatus()
Determine the status category that contains the given state.
public
resolveStatus(string $state, array<string|int, mixed> $statuses) : string|null
Parameters
- $state : string
-
The state to look up.
- $statuses : array<string|int, mixed>
-
Map of status => [states].
Return values
string|null —The status category, or null if not found.
validateRequiredFields()
Validate that all required fields for a state transition are present and non-empty.
public
validateRequiredFields(array<string|int, mixed> $entityData, array<string|int, mixed> $requiredFields) : array<string|int, mixed>
Parameters
- $entityData : array<string|int, mixed>
-
The entity data to check.
- $requiredFields : array<string|int, mixed>
-
List of field names that must be present.
Return values
array<string|int, mixed> —List of missing/empty field names. Empty array means valid.
validateTransition()
Check whether a transition from one state to another is allowed.
public
validateTransition(string $currentState, string $targetState, array<string|int, mixed> $config) : bool
Parameters
- $currentState : string
-
The entity's current state.
- $targetState : string
-
The desired target state.
- $config : array<string|int, mixed>
-
The state machine configuration containing 'transitions'.