Blog Detail


Advanced State Support for Laravel Eloquent Models by Spatie cover image

Advanced State Support for Laravel Eloquent Models by Spatie

Laravel Model States is a package by Spatie that 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.


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 Example

To give you a feel for 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 the 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 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()
            ->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);


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

For more details, Please visit its documentation here.

Published at : 02-11-2022

Author : Rizwan Aslam
Rizwan Aslam

I am a highly results-driven professional with 12+ years of collective experience in the grounds of web application development especially in laravel, native android application development in java, and desktop application development in the dot net framework. Now managing a team of expert developers at Codebrisk.

Launch project