Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mouadziani/xstate
✨ A lightweight state machine library for PHP (inspired by xstate.js)
https://github.com/mouadziani/xstate
Last synced: 9 days ago
JSON representation
✨ A lightweight state machine library for PHP (inspired by xstate.js)
- Host: GitHub
- URL: https://github.com/mouadziani/xstate
- Owner: mouadziani
- License: mit
- Created: 2022-04-22T20:43:28.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-07-08T21:53:01.000Z (5 months ago)
- Last Synced: 2024-11-11T20:35:13.903Z (about 1 month ago)
- Language: PHP
- Homepage:
- Size: 162 KB
- Stars: 85
- Watchers: 2
- Forks: 5
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
Awesome Lists containing this project
- awesome-morocco - Xstate - A [state machine](https://statecharts.dev/what-is-a-state-machine.html) library to play with any complex behavior of your PHP objects (inspired from [xstate.js](https://github.com/statelyai/xstate)). by [@mouadziani](https://github.com/mouadziani) (Uncategorized / Uncategorized)
README
## XState - State Machine for PHP
XState is a [state machine](https://statecharts.dev/what-is-a-state-machine.html) library to play with any complex behavior of your PHP objects (inspired by [xstate.js](https://github.com/statelyai/xstate))
### Installation
The recommended way to install Xstate is through
[Composer](https://getcomposer.org/)
```bash
composer require mouadziani/xstate
```
### Define state machine workflow
Let's say we want to define a state machine workflow for a video object, generally a video may have 3 states (playing, stopped, paused),
as a first step you have to create a new object from `StateMachine` class
```php
use \Mouadziani\XState\StateMachine;
$video = StateMachine::make();
```
Then you have to define the allowed states as well as the default state
```php
$video
->defaultState('stopped')
->states(['playing', 'stopped', 'paused']);
```
And finally the transitions
```php
use \Mouadziani\XState\Transition;
$video->transitions([
new Transition('PLAY', ['stopped', 'paused'], 'playing'),
new Transition('STOP', 'playing', 'stopped'),
new Transition('PAUSE', 'playing', 'paused'),
new Transition('RESUME', 'paused', 'playing'),
]);
```
The `Transition` class expect 3 required params:
- **Trigger**: As a name of the transition which will be used to trigger a specific transition *(should be unique)*
- **From**: Expect a string for a single / or array for multiple initial allowed states
- **To**: Expect string which is the next target state *(should match one of the defined allowed states)*
#### Guards (optional)
You can either define a guard callback for a specific transition using `guard` method, which must return a bool. If a guard returns false, the transition cannot be performed.
```php
use \Mouadziani\XState\Transition;
$video->transitions([
(new Transition('PLAY', ['stopped', 'paused'], 'playing'))
->guard(function ($from, $to) {
return true;
})
]);
```
### 💡 You can define the whole workflow using a single statement:
```php
$video = StateMachine::make()
->defaultState('playing')
->states(['playing', 'stopped', 'paused'])
->transitions([
new Transition('PLAY', ['stopped', 'paused'], 'playing'),
new Transition('STOP', 'playing', 'stopped'),
new Transition('PAUSE', 'playing', 'paused'),
]);
```
### Work with states & transitions
#### Trigger transition
There are two ways to trigger a specific defined transition
1- Using `transitionTo` method and specify the name of the transition as an argument
```php
$video->transitionTo('PLAY');
```
2- Or just calling the name of the transition from your machine object as a method
```php
$video->play();
```
Occasionally triggering a transition may throw an exception if the target transition is not defined /or not allowed:
```php
use \Mouadziani\XState\Exceptions;
try {
$video->transitionTo('RESUME');
} catch (Exceptions\TransitionNotDefinedException $ex) {
// the target transition is not defined
} catch (Exceptions\TransitionNotAllowedException $ex) {
// the target transition is not allowed
}
```
#### Get the current state
```php
echo $video->currentState(); // playing
```
#### Get the allowed transitions
```php
$video->allowedTransitions(); // ['STOP', 'PAUSE']
```
#### Adding in-demand transition
```php
$video->addTransition(new Transition('TURN_OFF', 'playing', 'stopped'));
```
## Upcoming features
- [x] Add the ability to define guard for a specific transition
- [ ] Define/handle hooks before/after triggering transition
## Testing
```bash
composer test
```
## Security Vulnerabilities
Please review [our security policy](../../security/policy) on how to report security vulnerabilities.
## Credits
- [Mouad Ziani](https://github.com/mouadziani)
- [All Contributors](../../contributors)
## License
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.
featured_repository