Download the PHP package dor-denis/validated-statemachine without Composer
On this page you can find all versions of the php package dor-denis/validated-statemachine. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download dor-denis/validated-statemachine
More information about dor-denis/validated-statemachine
Files in dor-denis/validated-statemachine
Package validated-statemachine
Short Description Configurable state machine with ability to validate transitions
License MIT
Informations about the package validated-statemachine
Validated Statemachine for PHP
A simple statemachine with ability to validate transitions.
Usage
You can add the State Machine behavior to any PHP class by using StateMachine trait provided by this package.
You'll need to implement two methods:
-
- returns a string with the name of property holding the state value
-
- returns an instance of the class extending StateMachineSpecification
State Property
If your project uses some kind of ActiveRecord approach to store models, the state value can be also persisted to the DB. To set initial state of the state machine, set default value of your property to it.
State Machine Trait
StateMachine trait offers you next methods:
- setState() - sets current state of the model
- getState() - gets current state of the model (as State instance)
- getAvailableTransitions() - gets available transitions of the current model (as array of Transition objects)
- canExecuteTransition() - whether it is possible to execute a transition given as a param
- executeTransition() - execute the transition, returns or upon success/fail.
- getValidationError() - returns the validator class name which failed during last transition attempt.
For example of usage, see example/ folder
State Machine Specification
The state machine specification is basically a configuration of your state machine which lists all possible states and transitions between them.
The example is listed below
We've set state names to numbers so we could later sort them in DB by priority. You can also use strings or that.
In StateMachineSpecification class, you need to implement two methods:
- getStateDefinitions - returns array where keys are state names and values are payloads of each state (will be available to you when you'll call the getState() methon on StateMachine model). Can be also an array of State objects
- getTransitionDefinitions - returns array where keys are transition names, and values are arrays with next obligatory keys:
- from - the state name from which the model can go with this transition;
- to - the state name to which the model can go with this transition;
- validators - the class names or instances of classes implementing Validator interface, and params for them (discussed below)
- Remark: can be also an array of Transition objects
Validators
You can validate your transitions by mentioning classes implementing Validator interface in key of result array.
While performing the transition, the validators are being iterated and executed. If at least one validator returns false in the method, the property of the state machine model will tell you which validator failed, and the method will return false
An example of the Validator:
The parameters passed to validator are Transition object and the state machine model.
If some params are passed to validator (like exampleParam in Validator1 in the example), they will be passed to method of the validator.
Events
The Symfony's EventDispatcher events are thrown:
- transition.executed - when the transition has been successfully executed
- transition.failed - if the transition failed
To subscribe to events, use object. For more info on Symfony event dispatcher, check out it's documentation
Visualization
The HtmlVisualization class allows you to create a visualization for your state machine using the sigma.js library. It is using ForceAtlas2 algorithm to distribute the states (the nodes of the graph) and then you can drag them as you like. After that you can print the result.