Introduction | laravel-model-states | Spatie

 SPATIE

  Laravel Model States
=======================

spatie.be/open-source

  [Docs](https://spatie.be/docs)  [Laravel-model-states](https://spatie.be/docs/laravel-model-states/v1)  Introduction

 Version   v2   v1

 Other versions for crawler [v2](https://spatie.be/docs/laravel-model-states/v2) [v1](https://spatie.be/docs/laravel-model-states/v1)

- [ Introduction ](https://spatie.be/docs/laravel-model-states/v1/01-introduction)
- [ Postcardware ](https://spatie.be/docs/laravel-model-states/v1/02-postcardware)
- [ Requirements ](https://spatie.be/docs/laravel-model-states/v1/03-requirements)
- [ Installation & setup ](https://spatie.be/docs/laravel-model-states/v1/04-installation-setup)
- [ Questions and issues ](https://spatie.be/docs/laravel-model-states/v1/05-questions-issues)
- [ Changelog ](https://spatie.be/docs/laravel-model-states/v1/06-changelog)
- [ About us ](https://spatie.be/docs/laravel-model-states/v1/07-about-us)

Working with states
-------------------

- [ Configuring states ](https://spatie.be/docs/laravel-model-states/v1/working-with-states/01-configuring-states)
- [ Serializing states ](https://spatie.be/docs/laravel-model-states/v1/working-with-states/02-serializing-states)
- [ Listing states ](https://spatie.be/docs/laravel-model-states/v1/working-with-states/03-listing-states)

Working with transitions
------------------------

- [ Configuring transitions ](https://spatie.be/docs/laravel-model-states/v1/working-with-transitions/01-configuring-transitions)
- [ Custom transition classes ](https://spatie.be/docs/laravel-model-states/v1/working-with-transitions/02-custom-transition-classes)
- [ Dependency injection in transition classes ](https://spatie.be/docs/laravel-model-states/v1/working-with-transitions/03-dependency-injection-in-transition-classes)
- [ Retrieving transitionable states ](https://spatie.be/docs/laravel-model-states/v1/working-with-transitions/04-retrieving-transitionable-states)

Querybuilder support
--------------------

- [ State scopes ](https://spatie.be/docs/laravel-model-states/v1/querybuilder-support/01-state-scopes)

Request validation
------------------

- [ State validation rule ](https://spatie.be/docs/laravel-model-states/v1/request-validation/01-state-validation-rule)

      You are viewing the documentation for **an older version** of this package. You can check the version you are using with the following command:

 `                                    composer show spatie/laravel-model-states                                                                                                                                                                                                                                    `

 Laravel Model States
======================

 Adding state behaviour to Eloquent models

 [    Repository ](https://github.com/spatie/laravel-model-states)

    6,270,979

    1,277

Introduction
------------

###  On this page

1. [ We have badges! ](#content-we-have-badges)

This package adds state support to models. It combines concepts from the [state pattern](https://en.wikipedia.org/wiki/State_pattern) and [state machines](https://www.youtube.com/watch?v=N12L5D78MAA).

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 and controller state transitions.

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

Here's what the `Payment` model would look like:

```
use Spatie\ModelStates\HasStates;

/**
 * @property \App\States\PaymentState $state
 */
class Payment extends Model
{
    use HasStates;

    protected function registerStates(): void
    {
        $this
            ->addState('state', PaymentState::class)
            ->allowTransition(Pending::class, Paid::class)
            ->allowTransition(Pending::class, Failed::class, PendingToFailed::class);
    }
}
```

This is what the abstract `PaymentState` class would look like:

```
use Spatie\ModelStates\State;

abstract class PaymentState extends State
{
    abstract public function color(): string;
}
```

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 it used:

```
$payment = Payment::find(1);

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

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

There's a lot more to tell about how this package can be used. So let's dive in.

We have badges!
---------------------------------------------------------------------------------------------------

 [![Latest Version](https://img.shields.io/github/release/spatie/laravel-model-states.svg?style=flat-square)](https://github.com/spatie/laravel-model-states/releases) [![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)](https://github.com/spatie/laravel-model-states/blob/master/LICENSE.md) [![Build Status](https://img.shields.io/github/workflow/status/spatie/laravel-model-states/run-tests?label=tests)](https://github.com/spatie/laravel-model-states/actions?query=workflow%3Arun-tests+branch%3Amaster) [![Quality Score](https://img.shields.io/scrutinizer/g/spatie/laravel-model-states.svg?style=flat-square)](https://scrutinizer-ci.com/g/spatie/laravel-model-states) [![Total Downloads](https://img.shields.io/packagist/dt/spatie/laravel-model-states.svg?style=flat-square)](https://packagist.org/packages/spatie/laravel-model-states)