Eloquent State Machines

December 08, 2020 / Paul Redmond

Eloquent State Machines is a package by Andrés Santibáñez that simplifies transitioning the states of Eloquent models:

During this weekend, I started working on a new package for @laravelphp to manage state machines for Eloquent models. Had so much fun and learned a ton in the process.

I've just tagged v1.0.0. Enjoy!https://t.co/9CrZ4azz3C

Feedback welcomed!

— Andrés Santibáñez (@asantibanez) December 7, 2020

Transitioning states is accomplished by defining the transition logic in a specific state machine. Here’s an example from the readme of a SalesOrder model:

// 'pending', 'approved', 'declined' or 'processed'
$salesOrder->status;
// null, 'pending', 'completed'
$salesOrder->fulfillment;

//
// Transition state examples
//

$salesOrder->status()->transitionTo('approved');
$salesOrder->fulfillment()->transitionTo('completed');

// Transition with custom properties
$salesOrder->status()->transitionTo('approved', [
    'comments' => 'Customer has available credit',
]);

Here are some examples of checking the transition history:

$salesOrder->status()->was('approved');
$salesOrder->status()->timesWas('approved');
$salesOrder->status()->whenWas('approved');
$salesOrder->fulfillment()->snapshowWhen('completed');
$salesOrder->status()->history()->get();

Finally, here’s an example of how a model might consume this package:

namespace App\Models;

use App\StateMachines\SalesOrders\StatusStateMachine;
use Asantibanez\LaravelEloquentStateMachines\Traits\HasStateMachines;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;

class SalesOrder extends Model
{
    use HasFactory;
    use HasStateMachines;

    public $stateMachines = [
        'status' => StatusStateMachine::class,
    ];
}

Andrés has a demo application available to demonstrate how to use this package with Laravel. You can learn more about this package, get full installation instructions, and view the source code on GitHub.