Download the PHP package norotaro/enumata without Composer
On this page you can find all versions of the php package norotaro/enumata. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download norotaro/enumata
More information about norotaro/enumata
Files in norotaro/enumata
Package enumata
Short Description State machines for Eloquent models with Enums
License MIT
Informations about the package enumata
Enumata
State Machines for Eloquent models using Enums.
Table of Contents
- Enumata
- Table of Contents
- Description
- Live demo
- Installation
- Basic usage
- The State Definition file - enum file
- Configuring the model
- Access the current state
- Transitioning
- Disable default transition methods
- Transition not allowed exception
- Force transitions
- Nullable States
- Create a State Definition file
- Register the State Definition file
- The State Machine
- Using the State Machine
- Transitioning
- Checking available transitions
- Events
- Listening to events using
$dispatchesEvents
- Listening to events using Closures
- Testing
- Inspiration
- LICENSE
Description
This package helps to implement State Machines to Eloquent models in an easy way using Enum files to represent all possible states and also to configure transitions.
Live demo
You can check the norotaro/enumata-demo repository or go to the live version of the demo in this PHP Sandbox.
Installation
Basic usage
Having a model with a status
field and 4 possible states:
We need to create an enum
file with the State Definitions which we will call OrderStatus
.
We can do this with the make:model-state
command:
The State Definition file - enum file
The above command will create a default file that we can adapt to meet our needs:
The transitions()
method must return an array with key=>value
where the key is the name of the transition and the value is the state to apply in that transition.
Note that, by default, methods will be created in the model for each transition. In the case of the example, the
approve()
,decline()
, andprocessOrder()
methods will be created.
Configuring the model
In the model we have to implement the contract HasStateMachine
and register the EloquentHasStateMachines
trait and then the enum
file in the $casts
property:
That's it! Now we can transition between the states.
Access the current state
If you access the attributes, Eloquent will return the enum
object with the current state:
Transitioning
By default this package will create methods in the model for each transition returned by transitions()
so, for this example, we will have these methods available:
Disable default transition methods
You can disable the creation of transition methods by making the $defaultTransitionMethods
attribute of the model false
.
Internally these methods use the transitionTo($state)
method available in the StateMachine
class, so you can implement your custom transition methods with it.
Transition not allowed exception
If a transition is applied and the current state does not allow it, the TransitionNotAllowedException
will be thrown.
Force transitions
All the methods of transitions created by the trait and also the transitionTo()
method have the force
parameter which, when true, the transition is applied without checking the defined rules.
Nullable States
If the model has nullable states we only have to implement the Norotaro\Enumata\Contracts\Nullable
contract in the State Definition file.
As an example, we will add the fulfillment
attribute to the Order model:
Create a State Definition file
We can create the enum file with the make:model-state
command and the --nullable
option:
After editing the generated file we can have something like this:
The initialTransitions()
method must return the list of available transitions when the field is null.
As with
transitions()
, by default methods will be created with the name of the keys returned byinitialTransitions()
.
Register the State Definition file
As we previously did with the status
definition, we need to register the file in the $casts
property:
The State Machine
To access the State Machine we only need to add parentheses to the attribute name:
If the attribute uses underscore such as
my_attribute
, you can access the state machine using the camel case name of the attribute,myAttribute()
in this case.
Using the State Machine
Transitioning
We can transition between states with the transitionTo($state)
method:
Checking available transitions
Events
This package adds two new events to those dispatched by Eloquent by default and can be used in the same way.
More information about Eloquent Events can be found in the official documentation.
transitioning:{attribute}
: This event is dispatched before saving the transition to a new state.transitioned:{attribute}
: This event is dispatched after saving the transition to a new state.
In the transitioning
event you can access the original and the new state in this way:
Listening to events using $dispatchesEvents
Listening to events using Closures
The transitioning($field, $callback)
and transitioned($field, $callback)
methods help to register closures.
Note that the first parameter must be the name of the field we want to listen to.
Testing
To run the test suite:
Inspiration
This package was inspired by asantibanez/laravel-eloquent-state-machines.
LICENSE
The MIT License (MIT). Please see License File for more information.
All versions of enumata with dependencies
illuminate/support Version ^10.0|^11.0|^12.0
javoscript/laravel-macroable-models Version ^1.0