datomatic / laravel-enum-state-machine
A simple state machine for enums in Laravel
Fund package maintenance!
Datomatic
Requires
- php: ^8.2
- illuminate/contracts: ^10.0||^11.0
- spatie/laravel-package-tools: ^1.16
Requires (Dev)
- datomatic/laravel-enum-helper: ^2.0
- larastan/larastan: ^2.9
- laravel/pint: ^1.14
- nunomaduro/collision: ^8.1.1||^7.10.0
- orchestra/testbench: ^9.0.0||^8.22.0
- pestphp/pest: ^2.34
- pestphp/pest-plugin-arch: ^2.7
- pestphp/pest-plugin-laravel: ^2.3
- phpstan/extension-installer: ^1.3
- phpstan/phpstan-deprecation-rules: ^1.1
- phpstan/phpstan-phpunit: ^1.3
- spatie/laravel-ray: ^1.35
README
Laravel enum state machine
This package it's simple state transitions control for enums in Laravel, this is not an implementation of state machine pattern. Allowing you to prevent unlogically transition and also controlling the initial state of the enum fields on your models.
Installation
Laravel 10+ and PHP 8.2+ are required.
You can install the package via composer:
composer require datomatic/laravel-enum-state-machine
You can publish and run the migrations with:
php artisan vendor:publish --tag="enum-state-machine-migrations"
php artisan migrate
You can publish the config file with:
php artisan vendor:publish --tag="enum-state-machine-config"
This is the contents of the published config file:
return [ /* |-------------------------------------------------------------------------- | Soft Mode Configuration |-------------------------------------------------------------------------- | | The 'soft_mode' configuration allows for handling errors without | interrupting the application's execution. When this option is enabled, | no exceptions are thrown during state transitions and logged instead. | This helps prevent unexpected crashes, ensuring | greater application resilience, especially in scenarios where a failure | in the state machine should not disrupt the main program flow. | You can configure this modality for each model casting | */ 'soft_mode' => env('LARAVEL_ENUM_STATE_MACHINE_SOFT_MODE', false), ];
Using Laravel IDE Helper?
If you are using Laravel IDE Helper, you need to run the following command:
php artisan vendor:publish --tag="enum-state-machine-ide-helper-hooks"
and add LaravelEnumStateMachineModelIdeHelperHook::class
on model_hooks
array in config/ide-helper.php
'model_hooks' => [
...,
LaravelEnumStateMachineModelIdeHelperHook::class,
],
Usage
Laravel enum state machine it's a simple state transitions control for enums in Laravel, this is not an implementation of state machine pattern.
In the default mode, if the transition is not allowed, an exception StatusTransitionDenied
will be thrown.
In the soft mode, if the transition is not allowed, an error message will be logged.
Setting the model
You need to define the casts in your model and the transition control function. The first param on the casting is the enum class and the optional second param is the soft mode modality (if no second param is passed, the default mode configured in config file is used). You can cast multiple fields if needed. The transition method name is composed by the enum field name (camelCase) + Transitions and serve to define whether a transition is allowed or not.
class TestModel extends Model { //Laravel 10 protected $casts = [ 'status' => AsEnumStateMachine::class.':'.StatusEnum::class, // ',true' for soft mode ]; //Laravel 11 protected function casts(): array { return [ 'field_name' => AsEnumStateMachine::of(FieldEnum::class, false), ]; } /** * This method name is composed by the enum field name (camelCase) + Transitions */ public function statusTransitions(?StatusEnum $from, ?StatusEnum $to): bool { return match ($from) { null => true, // initial state permitted to all states StatusEnum::PUBLIC => match ($to) { StatusEnum::PRIVATE => true, StatusEnum::PROTECTED => true, null => false, default => false }, StatusEnum::PROTECTED => match ($to) { StatusEnum::PRIVATE => true, StatusEnum::PUBLIC => false, default => false }, StatusEnum::PRIVATE => false, //final state default => true }; }
Use the model
$model = new TestModel; $model->status = StatusEnum::PUBLIC; // OK $model->save(); $model = TestModel::find(1); $model->status; // StatusEnum::PUBLIC $model->status = StatusEnum::PRIVATE; // OK $model->status = StatusEnum::PUBLIC; // thrown `StatusTransitionDenied`
Testing
composer test
Changelog
Please see CHANGELOG for more information on what has changed recently.
Security Vulnerabilities
Please review our security policy on how to report security vulnerabilities.
Credits
License
The MIT License (MIT). Please see License File for more information.