Download the PHP package norotaro/enumata without Composer

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(), and processOrder() 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 by initialTransitions().

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.