PHPackages                             aw-studio/laravel-states - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. aw-studio/laravel-states

ActiveLibrary[Utility & Helpers](/categories/utility)

aw-studio/laravel-states
========================

v1.6.0(7mo ago)445.6k[1 issues](https://github.com/aw-studio/laravel-states/issues)MITPHP

Since Feb 22Pushed 7mo ago2 watchersCompare

[ Source](https://github.com/aw-studio/laravel-states)[ Packagist](https://packagist.org/packages/aw-studio/laravel-states)[ RSS](/packages/aw-studio-laravel-states/feed)WikiDiscussions main Synced 2d ago

READMEChangelog (10)Dependencies (5)Versions (23)Used By (0)

Laravel States
==============

[](#laravel-states)

A package to make use of the **finite state pattern** in eloquent Models.

The package stores all states in a database table, so all states changes and the corresponding times can be traced. Since states are mapped via a relation, no additional migrations need to be created when a new state is needed for a model.

A Recommendation
----------------

[](#a-recommendation)

Use states wherever possible! A state can be used instead of booleans like `active` or timestamps like `declined_at` or `deleted_at`:

```
$product->state->is('active');
```

This way you also know when the change to active has taken place. Also your app becomes more scalable, you can simply add an additional state if needed.

Table Of Contents
-----------------

[](#table-of-contents)

- [Setup](#setup)
- [Basics](#basics)
- [Usage](#usage)
    - [Receive The Current State](#receive-state)
    - [Execute Transitions](#execute-transitions)
    - [Eager Loading](#eager-loading)
    - [Query Methods](#query)
- [Observer Events](#events)

Setup
-----

[](#setup)

1. Install the package via composer:

```
composer require aw-studio/laravel-states
```

2. Publish the required assets:

```
php artisan vendor:publish --tag="states:migrations"
```

3. Run The Migrations

```
php artisan migrate
```

Basics
------

[](#basics)

1. Create A State:

```
class BookingState extends State
{
    const PENDING = 'pending';
    const FAILED = 'failed';
    const SUCCESSFULL = 'successfull';

    const INITIAL_STATE = self::PENDING;
    const FINAL_STATES = [self::FAILED, self::SUCCESSFULL];
}
```

2. Create the transitions class:

```
class BookingStateTransitions extends State
{
    const PAYMENT_PAID = 'payment_paid';
    const PAYMENT_FAILED = 'payment_failed';
}
```

3. Define the allowed transitions:

```
class BookingState extends State
{
    // ...

    public static function config()
    {
        self::set(BookingStateTransition::PAYMENT_PAID)
            ->from(self::PENDING)
            ->to(self::SUCCESSFULL);
        self::set(BookingStateTransition::PAYMENT_FAILED)
            ->from(self::PENDING)
            ->to(self::FAILED);
    }
}
```

4. Setup your Model:

```
use AwStudio\States\Contracts\Stateful;
use AwStudio\States\HasStates;

class Booking extends Model implements Stateful
{
    use HasStates;

    protected $states = [
        'state' => BookingState::class,
        'payment_state' => ...,
    ];
}
```

Usage
-----

[](#usage)

### Receive The Current State

[](#receive-the-current-state)

```
$booking->state->current(); // "pending"
(string) $booking->state; // "pending"
```

Determine if the current state is a given state:

```
if($booking->state->is(BookingState::PENDING)) {
    //
}
```

Determine if the current state is any of a the given states:

```
$states = [
    BookingState::PENDING,
    BookingState::SUCCESSFULL
];
if($booking->state->isAnyOf($states)) {
    //
}
```

Determine if the state has been the given state at any time:

```
if($booking->state->was(BookingState::PENDING)) {
    //
}
```

### Execute Transitions

[](#execute-transitions)

Execute a state transition:

```
$booking->state->transition(BookingStateTransition::PAYMENT_PAID);
```

Prevent throwing an exception when the given transition is not allowed for the current state by setting fail to `false`:

```
$booking->state->transition(BookingStateTransition::PAYMENT_PAID, fail: false);
```

Store additional information about the reason of a transition.

```
$booking->state->transition(BookingStateTransition::PAYMENT_PAID, reason: "Mollie API call failed.");
```

Determine wether the transition is allowed for the current state:

```
$booking->state->can(BookingStateTransition::PAYMENT_PAID);
```

Lock the current state for update at the start of a transaction so the state can not be modified by simultansiously requests until the transaction is finished:

```
DB::transaction(function() {
    // Lock the current state for update:
    $booking->state->lockForUpdate();

    // ...
});
```

### Eager Loading

[](#eager-loading)

Reload the current state:

```
$booking->state->reload();
```

Eager load the current state:

```
Booking::withCurrentState();
Booking::withCurrentState('payment_state');

$booking->loadCurrentState();
$booking->loadCurrentState('payment_state');
```

### Query Methods

[](#query-methods)

Filter models that have or dont have a current state:

```
Booking::whereStateIs('payment_state', PaymentState::PAID);
Booking::orWhereStateIs('payment_state', PaymentState::PAID);
Booking::whereStateIsNot('payment_state', PaymentState::PAID);
Booking::orWhereStateIsNot('payment_state', PaymentState::PAID);
Booking::whereStateWas('payment_state', PaymentState::PAID);
Booking::whereStateWasNot('payment_state', PaymentState::PAID);
```

Receive state changes:

```
$booking->states()->get() // Get all states.
$booking->states('payment_state')->get() // Get all payment states.
```

Observer Events
---------------

[](#observer-events)

Listen to state changes or transitions in your model observer:

```
class BookingObserver
{
    public function stateSuccessfull(Booking $booking)
    {
        // Gets fired when booking state changed to successfull.
    }

    public function paymentStatePaid(Booking $booking)
    {
        // Gets fired when booking payment_state changed to paid.
    }

    public function stateTransitionPaymentPaid(Booking $booking)
    {
        // Gets fired when state transition payment_paid gets fired.
    }
}
```

Static Methods:
---------------

[](#static-methods)

```
BookingState::whereCan(BookingStateTransition::PAYMENT_PAID); // Gets states where from where the given transition can be executed.
BookingState::canTransitionFrom('pending', 'cancel'); // Determines if the transition can be executed for the given state.
```

###  Health Score

44

—

FairBetter than 92% of packages

Maintenance62

Regular maintenance activity

Popularity27

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity62

Established project with proven stability

 Bus Factor1

Top contributor holds 82.1% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~104 days

Recently: every ~319 days

Total

17

Last Release

231d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/29352871?v=4)[Lennart Carstens-Behrens](/maintainers/cbl)[@cbl](https://github.com/cbl)

---

Top Contributors

[![cbl](https://avatars.githubusercontent.com/u/29352871?v=4)](https://github.com/cbl "cbl (64 commits)")[![jannescb](https://avatars.githubusercontent.com/u/17292622?v=4)](https://github.com/jannescb "jannescb (11 commits)")[![lpheller](https://avatars.githubusercontent.com/u/36259611?v=4)](https://github.com/lpheller "lpheller (3 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/aw-studio-laravel-states/health.svg)

```
[![Health](https://phpackages.com/badges/aw-studio-laravel-states/health.svg)](https://phpackages.com/packages/aw-studio-laravel-states)
```

###  Alternatives

[barryvdh/laravel-ide-helper

Laravel IDE Helper, generates correct PHPDocs for all Facade classes, to improve auto-completion.

14.9k123.0M687](/packages/barryvdh-laravel-ide-helper)[orchestra/canvas

Code Generators for Laravel Applications and Packages

21017.2M158](/packages/orchestra-canvas)[kirschbaum-development/commentions

A package to allow you to create comments, tag users and more

12369.2k](/packages/kirschbaum-development-commentions)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

255.2k](/packages/aedart-athenaeum)[glhd/special

1929.4k](/packages/glhd-special)[bjuppa/laravel-blog

Add blog functionality to your Laravel project

483.3k2](/packages/bjuppa-laravel-blog)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)