README

Adding state behaviour to Eloquent models

This package adds state support to models. It combines concepts from the state pattern and state machines.

It is recommended that you're familiar with both patterns if you're going to use this package.

To give you a feel about how this package can be used, let's look at a quick example.

Imagine a model Payment, which has three possible states: Pending, Paid and Failed. This package allows you to represent each state as a separate class, handles serialization of states to the database behind the scenes, and allows for easy state transitions.

For the sake of our example, let's say that, depending on the state, the color of a payment should differ.

Here's what the Payment model would look like:

use Spatie\ModelStates\HasStates;

class Payment extends Model
{
    use HasStates;

    protected $casts = [
        'state' => PaymentState::class,
    ];
}

This is what the abstract PaymentState class would look like:

use Spatie\ModelStates\State;
use Spatie\ModelStates\StateConfig;

abstract class PaymentState extends State
{
    abstract public function color(): string;
    
    public static function config(): StateConfig
    {
        return parent::config()
            ->default(Pending::class)
            ->allowTransition(Pending::class, Paid::class)
            ->allowTransition(Pending::class, Failed::class)
        ;
    }
}

Here's a concrete implementation of one state, the Paid state:

class Paid extends PaymentState
{
    public function color(): string
    {
        return 'green';
    }
}

And here's how it is used:

$payment = Payment::find(1);

$payment->state->transitionTo(Paid::class);

echo $payment->state->color();

Support us

We invest a lot of resources into creating best in class open source packages. You can support us by buying one of our paid products.

We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on our contact page. We publish all received postcards on our virtual postcard wall.

Installation

You can install the package via composer:

composer require spatie/laravel-model-states

You can publish the config file with:

php artisan vendor:publish --provider="Spatie\ModelStates\ModelStatesServiceProvider" --tag="model-states-config"

This is the content of the published config file:

return [

    /*
     * The fully qualified class name of the default transition.
     */
    'default_transition' => Spatie\ModelStates\DefaultTransition::class,

];

Usage

Please refer to the docs to learn how to use this package.

Testing

composer test

Changelog

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

Transition history (metadata & timestamps)

By default, Model States only stores the current state value on your model.

If you want to keep a transition log with per-transition timestamps and optional metadata, you can opt-in to transition history storage.

Setup

Publish the migration: php artisan vendor:publish --tag=laravel-model-states-migrations
Run migrations: php artisan migrate
Enable in config/model-states.php:

'transition_history' => [
    'enabled' => true,
],

Writing metadata

$model->status->transitionTo(Published::class, metaData: [
    'approved_by' => 5,
    'comment' => 'Reviewed',
]);

Reading metadata and timestamps

$model->status->metaData();  // array|null
$model->status->createdAt(); // DateTimeInterface|null

When transition history is disabled (the default), no transitions are stored and both methods return null.

Contributing

Please see CONTRIBUTING for details.

Security

If you've found a bug regarding security please mail security@spatie.be instead of using the issue tracker.

Credits

License

The MIT License (MIT). Please see License File for more information.

theahmedy / laravel-model-states

Maintainers

Details