README

Simple state machine / resilient states for your Laravel application!

Installation

You can install the package via composer:

composer require louishrg/state-flow

Create your states classes with artisan :

Creating files for every available states is repetitive, that's why this package provide an artisan command to speed up the process :

php artisan states:new

Simple states AKA Stack

A Stack is a simple state machine that doesn't need to register transitions. It's a very convenient way to add a hardcoded type or category to your model.

How to use :

You need at least 1 variable: key which is the real value of the column in the database.

If you want to use other variables as key, you can give the name of the variable in you stateStack creation (see below)

First parameter is all your available state as an array.
Second parameter is the default value when creating a model (optional).
Third parameter is to override the default key-value (optional).

new Stack(self::$status, Pending::class, 'key'),

Declare your states classes in the directory of your choice, for example :

namespace App\Models\States\User;

use Louishrg\StateFlow\StateAbstract;

class Active extends StateAbstract
{
    public $key = 'active';

    public $label = 'Active';
    public $color = 'green';
    // and everything you want !
    //
    public function computedField() {
        return $this->$label.$this->color;
    }
}

Now, add all the needed declaration in your model :

<?php

...

// Import all your states
use App\Models\States\Active;
use App\Models\States\Banned;
use App\Models\States\Inactive;

// Import the classes
use Louishrg\StateFlow\Traits\WithState;
use Louishrg\StateFlow\Casts\StateCast;
use Louishrg\StateFlow\Stack;

class User
{
    // Add WithState trait
    use WithState, ...;

    ...

    // You can register all available states for a namespace in a var for example
    protected static $status = [
        Active::class,
        Banned::class,
        Inactive::class,
    ];

    // register your states as a Stack for the namespace "status"
    protected static function registerStates(){
        return [
            'status' => new Stack(self::$status),
        ];
    }

    ...

    // Add the cast for your column and that's it !
    protected $casts = [
        'status' => StateCast::class,
    ];
}

Now you can get your state like so :

$user->status;
// It'll give you the state object with all your defined constants in it.

If you want to update/create an object with a state:

$user = new User;

// Simply pass the state class and that's it.
$user->status = Pending::class;

Laravel Nova:

If you want to use the package in nova, you should use it as following :

Example with a select:

Select::make('Statut', 'status')
->options(GearRequest::getState('status')->pluck('label', 'key')->toArray())
->displayUsing(fn($item) => $item->label)
->resolveUsing(fn($item) => $item->key)
// Use the magic setter in the fillUsing method
->fillUsing(fn($request, $model) => ($model->_status = $request->status)),

Useful Methods :

If you want to compare the current value of a state with another one, you can use

$user->status->equal(Banned::class);

Also, you can directly get the class of your current state :

$user->status->is();

If you want to retrieve all your states registered in a namespace as a collection :

User::getState('status')

Complex States AKA Flow:

If you want to use the real state machine pattern in your app you can add register like so:

// Import the Flow class
use Louishrg\StateFlow\Flow;

...

protected static function registerStates(){
    return [
        // use a custom method in your model for better readability
        'status' => self::myFlow(),
    ];
}

// You need to use the Flow class
protected static function myFlow(){
    // We'll use the data from above
    return (new Flow(self::$status))
    // Add a transition, here your state can go from Pending to either Accepted or Refused.
    ->add(Pending::class, [
        Accepted::class,
        Refused::class
    ])
    ->add(Refused::class, [
        Pending::class
    ])
    ->add(Accepted::class, [
        Pending::class,
        Canceled::class,
        CanceledByAdmin::class
    ])
    ->default(Pending::class);
    // You can specify a default class, when creating you don't need to provide value.
}

Methods for flows :

When using flows, you can check if you can transition to another state like so :

$user->status->canBe(Banned::class);

Or you can get all the possible transitions for your current state :

$user->status->allowedTo();

Magic methods for your state :

When you are retrieving rows from your database, you new to instanciate your state to get the key :

$users = User::where('status', (new Active)->key)->get();

In order to simplify the syntax, every State values extend a StateAbstract that provide magic methods :

$users = User::where('status', Active::key())->get();

The magic methods can get you every property defined in your State

Features to come:

Possibility of using getter & setters in your state classes
Tests

Testing

composer test

Changelog

Please see CHANGELOG for more information about what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security-related issues, please email dev@narah.io instead of using the issue tracker.

louishrg / state-flow

Maintainers

Details