Laravel Eloquent State Machines

https://github.com/asantibanez/laravel-eloquent-state-machines
Admin
A Laravel package that simplifies state management for Eloquent models by defining transition logic...
Tokens:48,675
Snippets:381
Trust Score:9.1
License:MIT
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### transitions() example implementation

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/StateMachine.md

Example implementation of the transitions() method from tests/TestStateMachines/SalesOrders/StatusStateMachine.php. Shows a typical transition map with multiple target states for a single source state.

```php
public function transitions(): array
{
    return [
        'pending' => ['approved', 'waiting'],
        'approved' => ['processed'],
        'waiting' => ['cancelled'],
    ];
}
```

--------------------------------

### getCustomProperty usage example

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/StateHistory.md

Example of retrieving a custom property from a state history snapshot.

```php
$snapshot = $salesOrder->status()->snapshotWhen('approved');
$snapshot->getCustomProperty('comments'); // 'Customer has available credit'
```

--------------------------------

### Install and set up laravel-eloquent-state-machines

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/README.md

Install the package via Composer, publish its migration stubs using the given provider and tag, then run the database migrations to prepare required tables.

```bash
composer require asantibanez/laravel-eloquent-state-machines
```

```bash
php artisan vendor:publish --provider="Asantibanez\LaravelEloquentStateMachines\LaravelEloquentStateMachinesServiceProvider" --tag="migrations"
```

```bash
php artisan migrate
```

--------------------------------

### beforeTransitionHooks() example override

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/StateMachine.md

Example override of beforeTransitionHooks() from tests/TestStateMachines/SalesOrders/StatusWithBeforeTransitionHookStateMachine.php. Shows how to attach multiple callables to a specific $from state, each receiving ($to, $model).

```php
public function beforeTransitionHooks(): array
{
    return [
        'pending' => [
            function($to, $model) {
                $model->total = 100;
            },
            function($to, $model) {
                BeforeTransitionJob::dispatch();
            }
        ]
    ];
}
```

--------------------------------

### transitionTo usage examples

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/State.md

Shows basic usage, custom properties with responsible actor, and error handling for the transitionTo method.

```php
// Basic
$salesOrder->status()->transitionTo('approved');
```

```php
// With custom properties and responsible
$salesOrder->status()->transitionTo('approved', ['comments' => 'OK'], $user);
```

```php
// Error handling
try {
    $salesOrder->status()->transitionTo('declined');
} catch (TransitionNotAllowedException $e) {
    report($e);
}
```

--------------------------------

### Postpone transition example

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/StateMachine.md

Example of postponing a transition to 'approved' with a custom property and responsible user. The comment indicates the return type is PendingTransition|null.

```php
$pending = $salesOrder->status()->postponeTransitionTo(
    'approved',
    Carbon::now()->addDay(),
    ['comments' => 'Auto-approve tomorrow'],
    $responsible = auth()->user(),
     // → PendingTransition|null
);
```

--------------------------------

### Usage example for scheduling PendingTransitionsDispatcher

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/PendingTransitionsDispatcher.md

Usage example for scheduling the dispatcher in routes/console.php (Laravel 11+) or app/Console/Kernel.php. When the dispatcher runs, each due postponed transition becomes a PendingTransitionExecutor job on the default queue; the executor validates the starting state and applies the transition.

```php
// In routes/console.php (Laravel 11+) or app/Console/Kernel.php:
use Asantibanez\LaravelEloquentStateMachines\Jobs\PendingTransitionsDispatcher;

Schedule::job(PendingTransitionsDispatcher::class)->everyFiveMinutes();
```

--------------------------------

### validatorForTransition() example override

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/StateMachine.md

Example override of validatorForTransition() from tests/TestStateMachines/SalesOrders/FulfillmentStateMachine.php. Shows how to validate a transition by returning a Validator instance for specific from/to states, falling back to the parent implementation otherwise.

```php
use Illuminate\Contracts\Validation\Validator;
use Illuminate\Support\Facades\Validator as ValidatorFacade;

public function validatorForTransition($from, $to, $model): ?Validator
{
    if ($from === null && $to === 'pending') {
        return ValidatorFacade::make([
            'status' => $model->status,
        ], [
            'status' => Rule::in('approved'),
        ]);
    }

    return parent::validatorForTransition($from, $to, $model);
}
```

--------------------------------

### responsible usage example

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/StateHistory.md

Example of accessing the responsible actor from a state history snapshot.

```php
$salesOrder->status()->snapshotWhen('approved')->responsible; // User|null
```

--------------------------------

### Fetch Full Transition History with history()->get()

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/README.md

Gets the full history of state transitions as an Eloquent relationship. Chainable with scopes like from(), to(), and withCustomProperty().

```php
$salesOrder->status()->history()->get();
```

--------------------------------

### Transition States with transitionTo

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/README.md

Shows how to transition a state using the transitionTo method. The first two examples transition 'status' to 'approved' and 'fulfillment' to 'completed'. The third passes custom properties (e.g., comments), and the fourth passes a responsible user; if none is provided, auth()->user() is used by default.

```php
$salesOrder->status()->transitionTo('approved');

$salesOrder->fulfillment()->transitionTo('completed');

//With custom properties
$salesOrder->status()->transitionTo('approved', [
    'comments' => 'Customer has available credit',
]);

//With responsible
$salesOrder->status()->transitionTo('approved', [], $responsible); // auth()->user() by default
```

--------------------------------

### changedAttributes usage example

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/StateHistory.md

Example of retrieving changed attribute names and old/new values from the last history record.

```php
$last = $salesOrder->status()->history()->get()->last();
$last->changedAttributesNames();            // ['total', 'status']
$last->changedAttributeOldValue('total');   // 100
$last->changedAttributeNewValue('total');   // 200
```

--------------------------------

### Using field facade methods on model

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/HasStateMachines.md

Example usage of the dynamically registered field facade methods: checking state, transitioning, and checking if a state can be applied.

```php
$salesOrder->status()->is('pending');          // bool
$salesOrder->status()->transitionTo('approved');
$salesOrder->fulfillment_status()->canBe('pending');
```

--------------------------------

### SalesOrder model with stateMachines mapping

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/HasStateMachines.md

Example model using the HasStateMachines trait. The $stateMachines array maps field names to state machine classes.

```php
class SalesOrder extends Model
{
    use HasStateMachines;

    public $stateMachines = [
        'status' => StatusStateMachine::class,
        'fulfillment' => FulfillmentStateMachine::class,
    ];
}
```

--------------------------------

### Catch TransitionNotAllowedException for postponed transition

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/StateMachine.md

Error handling example for a disallowed postponed transition. Catches TransitionNotAllowedException and shows the from and to states in the exception.

```php
try {
    $salesOrder->status()->postponeTransitionTo('invalid', Carbon::tomorrow());
} catch (TransitionNotAllowedException $e) {
    // $e->getFrom() === 'pending', $e->getTo() === 'invalid'
}
```

--------------------------------

### transitionTo($from, $to, $customProperties = [], $responsible = null)

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/StateMachine.md

Transitions the model from a starting state to a target state, performing permission checks, validation, hooks, history recording, and cleanup. Returns void and throws TransitionNotAllowedException or ValidationException on failure.

```APIDOC
## [POST] transitionTo

### Description
Transitions the model from a starting state to a target state, performing permission checks, validation, hooks, history recording, and cleanup. Returns void and throws TransitionNotAllowedException or ValidationException on failure.

### Method
POST

### Endpoint
transitionTo

### Parameters
#### Path Parameters
- **$from** (string|null) - Required - Starting state (typically `$this->currentState()`)
- **$to** (string) - Required - Target state
- **$customProperties** (array) - Optional - Arbitrary key/value data stored on the history record. Default: []
- **$responsible** (mixed) - Optional - Actor that performed the transition; falls back to `auth()->user()`

### Request Example
```php
$salesOrder->status()->transitionTo('approved');

// With custom properties and explicit responsible
$salesOrder->status()->transitionTo('approved', [
    'comments' => 'Customer has available credit',
], $responsible = User::first());
```

### Response
#### Success Response (200)
- **void** - No return value

#### Error Response (400)
- **TransitionNotAllowedException** - Transition not permitted by the transitions() map (including wildcards)
- **ValidationException** - validatorForTransition() returned a validator that fails()

### Execution Order
1. Same-state short-circuit: if $to equals current state, return immediately.
2. Permission check: throws TransitionNotAllowedException if none of canBe($from, $to), canBe($from, '*'), canBe('*', $to), canBe('*', '*') pass.
3. Validation: validatorForTransition() fails throws ValidationException.
4. Before hooks: beforeTransitionHooks()[$from] callables invoked with ($to, $this->model).
5. Write: model field set to $to, changed attributes computed, model saved.
6. History: if recordHistory() is true, record state with responsible and changed attributes.
7. After hooks: afterTransitionHooks()[$to] callables invoked with ($from, $this->model).
8. Cleanup: cancelAllPendingTransitions().

### Parameters
#### Path Parameters
- **from** (string|null) - Required - Starting state (typically $this->currentState())
- **to** (string) - Required - Target state
- **customProperties** (array) - Optional - Arbitrary key/value data stored on the history record
- **responsible** (mixed) - Optional - Actor that performed the transition; falls back to auth()->user()

### Request Example
```php
$salesOrder->status()->transitionTo('approved');

// With custom properties and explicit responsible
$salesOrder->status()->transitionTo('approved', [
    'comments' => 'Customer has available credit',
], $responsible = User::first());
```

### Response
#### Success Response (200)
- Returns void on success.

#### Error Response (400)
- **TransitionNotAllowedException** - Thrown when the transition is not permitted by the transitions() map (including wildcards).
- **ValidationException** - Thrown when validatorForTransition() returns a validator that fails.

### Error Example
```php
try {
    $salesOrder->status()->transitionTo('declined'); // not allowed by transitions()
} catch (TransitionNotAllowedException $e) {
    $e->getFrom();   // 'pending'
    $e->getTo();     // 'declined'
    $e->getModel();  // 'App\Models\SalesOrder'
} catch (ValidationException $e) {
    // validatorForTransition() failed
}
```
```

--------------------------------

### custom_properties example

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/types.md

Example of the custom_properties array cast value. Stored as JSON in the custom_properties column. Accepted by transitionTo(), postponeTransitionTo(), and recordState(); queried via scopeWithCustomProperty().

```php
['comments' => 'Customer has available credit', 'approved_by' => ['id' => 1]]
```

--------------------------------

### Query Transition History with was, timesWas, whenWas, snapshotWhen, history

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/README.md

Shows methods for checking state history: was checks if the state was ever 'approved', timesWas returns the count, whenWas gives the timestamp, snapshotWhen retrieves a snapshot of the state, and history()->get() fetches the full history.

```php
$salesOrder->status()->was('approved');

$salesOrder->status()->timesWas('approved');

$salesOrder->status()->whenWas('approved');

$salesOrder->fulfillment()->snapshotWhen('completed');

$salesOrder->status()->history()->get();
```

--------------------------------

### Get State Snapshots with snapshotWhen() / snapshotsWhen()

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/README.md

Retrieves the latest snapshot or all snapshots for a given state using snapshotWhen() and snapshotsWhen().

```php
$salesOrder->status()->snapshotWhen('approved');

$salesOrder->status()->snapshotsWhen('approved');
```

--------------------------------

### Get Responsible for Past State with snapshotWhen()

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/README.md

Gets the responsible user for a past state transition using snapshotWhen($state). May be null in background jobs.

```php
$salesOrder->status()->snapshotWhen('approved')->responsible;
```

--------------------------------

### Query builder whereHas macro with state history scopes

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/HasStateMachines.md

Example of using the whereHasStatus and whereHasFulfillment macros to query models based on state history. The closure receives a StateHistory query pre-constrained with forField.

```php
SalesOrder::with([])
    ->whereHasStatus(function ($query) {
        $query
            ->withTransition('pending', 'approved')
            ->withResponsible(auth()->id());
    })
    ->whereHasFulfillment(function ($query) {
        $query->transitionedTo('complete');
    })
    ->get();
```

--------------------------------

### InvalidStartingStateException class definition

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/Exceptions.md

Defines the exception thrown when the model's current state does not match the expected starting state for a pending transition. The message includes the expected and actual states.

```php
class InvalidStartingStateException extends Exception
{
    public function __construct($expectedState, $actualState)
    {
        $message = "Expected: $expectedState. Actual: $actualState";

        parent::__construct($message);
    }
}
```

--------------------------------

### Dispatch PendingTransitionExecutor directly

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/PendingTransitionExecutor.md

Example of dispatching the PendingTransitionExecutor job directly with a PendingTransition obtained from postponeTransitionTo(). The job applies the transition when the queue worker processes it.

```php
use Asantibanez\LaravelEloquentStateMachines\Jobs\PendingTransitionExecutor;

$pending = $salesOrder->status()
    ->postponeTransitionTo('approved', Carbon::now(), ['comments' => 'All good!']);

PendingTransitionExecutor::dispatch($pending); // applies when the queue worker runs it
```

--------------------------------

### InvalidStartingStateException

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/Exceptions.md

Exception thrown when a pending transition's starting state does not match the model's current state. It is used internally by the job executor.

```APIDOC
## InvalidStartingStateException

### Description
Exception thrown when a pending transition's starting state does not match the model's current state. It is used internally by the job executor.

### Constructor
`__construct($expectedState, $actualState)`

### Parameters
- **$expectedState** (mixed) - Required - The expected starting state.
- **$actualState** (mixed) - Required - The actual current state.

### Exception Code
0 (default)

### Message Format
`Expected: {expectedState}. Actual: {actualState}`

### Usage Example
```php
// The executor marks the queue job as failed with this exception; the
// exception object is passed to your queue's failed job handler:
public function failed(InvalidStartingStateException $e)
{
    // Expected: pending. Actual: processed
    logger()->error($e->getMessage());
}
```
```

--------------------------------

### PendingTransitionExecutor job class

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/PendingTransitionExecutor.md

The full PendingTransitionExecutor job class. It implements ShouldQueue and uses the standard queue traits. The handle() method reads the pending transition's data, checks the starting state guard, and either fails the job with InvalidStartingStateException or applies the transition via transitionTo().

```php
class PendingTransitionExecutor implements ShouldQueue
{
    use InteractsWithQueue, Queueable, Dispatchable, SerializesModels;

    public $pendingTransition;

    public function __construct(PendingTransition $pendingTransition)
    {
        $this->pendingTransition = $pendingTransition;
    }

    public function handle()
    {
        $field = $this->pendingTransition->field;
        $model = $this->pendingTransition->model;
        $from = $this->pendingTransition->from;
        $to = $this->pendingTransition->to;
        $customProperties = $this->pendingTransition->custom_properties;
        $responsible = $this->pendingTransition->responsible;

        if ($model->$field()->isNot($from)) {
            $exception = new InvalidStartingStateException(
                $expectedState = $from,
                $actualState = $model->$field()->state()
            );

            $this->fail($exception);
            return;
        }

        $model->$field()->transitionTo($to, $customProperties, $responsible);
    }
}
```

--------------------------------

### Add transition validation with validatorForTransition()

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/README.md

Overrides validatorForTransition() to add validation before a transition. A Validator must be returned; if it fails, a ValidationException is thrown. The example validates that total > 0 when transitioning from 'pending' to 'approved'.

```php
use Illuminate\Support\Facades\Validator as ValidatorFacade;

class StatusStateMachine extends StateMachine
{
    public function validatorForTransition($from, $to, $model): ?Validator
    {
        if ($from === 'pending' && $to === 'approved') {
            return ValidatorFacade::make([
                'total' => $model->total,
            ], [
                'total' => 'gt:0',
            ]);
        }
        
        return parent::validatorForTransition($from, $to, $model);
    }
}
```

--------------------------------

### Publish and migrate state machine tables

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/configuration.md

Publishes the package's migration files (create_state_histories_table.php and create_pending_transitions_table.php) into database/migrations/ and then runs the migrations. The publish command only works when running in console.

```bash
php artisan vendor:publish --provider="Asantibanez\LaravelEloquentStateMachines\LaravelEloquentStateMachinesServiceProvider" --tag="migrations"
php artisan migrate
```

--------------------------------

### LaravelEloquentStateMachinesServiceProvider class

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/LaravelEloquentStateMachinesServiceProvider.md

Service provider that bootstraps the package. The boot() method publishes the create_state_histories_table and create_pending_transitions_table migrations and registers the MakeStateMachine command when running in console. Registered automatically via composer auto-discovery, so manual registration in config/app.php is normally not required.

```php
class LaravelEloquentStateMachinesServiceProvider extends ServiceProvider
{
    public function boot()
    {
        if ($this->app->runningInConsole()) {
            $this->publishes([
                __DIR__ . '/../database/migrations/create_state_histories_table.php.stub' => database_path('migrations/' . date('Y_m_d_His', time()) . '_create_state_histories_table.php'),
                __DIR__ . '/../database/migrations/create_pending_transitions_table.php.stub' => database_path('migrations/' . date('Y_m_d_His', time()) . '_create_pending_transitions_table.php'),
            ], 'migrations');

            $this->commands([
                MakeStateMachine::class,
            ]);
        }
    }

    public function register()
    {
        //
    }
}
```

--------------------------------

### Querying and inspecting pending transitions

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/PendingTransition.md

Shows how to query due pending transitions using the scopes and how to inspect a scheduled transition's attributes and relationships.

```php
use Asantibanez\LaravelEloquentStateMachines\Models\PendingTransition;

$due = PendingTransition::with(['model'])
    ->notApplied()
    ->onScheduleOrOverdue()
    ->get();

// Inspect a scheduled transition
$salesOrder->status()->pendingTransitions()->first();
// $pending->field, $pending->from, $pending->to, $pending->transition_at,
// $pending->custom_properties, $pending->responsible, $pending->model
```

--------------------------------

### Get Custom Property from Current State

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/README.md

Retrieves the custom property value for the current state.

```php
$salesOrder->status()->getCustomProperty('comments');
```

--------------------------------

### transitions() abstract method

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/StateMachine.md

Required abstract method that must be implemented by subclasses. Returns the transition map with 'from' => ['to', 'to', ...] pairs, where '*' acts as a wildcard for any state.

```php
abstract public function transitions() : array;
```

--------------------------------

### Get Custom Property from Past State

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/README.md

Retrieves a custom property from a previous state using snapshotWhen($state).

```php
$salesOrder->status()->snapshotWhen('approved')->getCustomProperty('comments');
```

--------------------------------

### Run tests with composer test

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/README.md

Runs the project test suite using Composer.

```bash
composer test
```

--------------------------------

### Initialize state machines

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/HasStateMachines.md

For each field in $stateMachines, instantiates the machine and assigns the default state when the attribute is not already set: $this->{$field} = $this->{$field} ?? $stateMachine->defaultState();.

```php
public function initStateMachines()
```

--------------------------------

### Empty package configuration file config/config.php

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/configuration.md

The published config/config.php file is intentionally empty. It is not loaded by the package and has no vendor:publish tag for config; it exists for future or optional use.

```php
<?php

/*
 * You can place your custom package configuration in here.
 */
return [

];
```

--------------------------------

### Get Responsible for Current State

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/README.md

Retrieves the responsible user for the current state transition. May be null when no auth()->user() is available, such as in background jobs.

```php
$salesOrder->status()->responsible();
```

--------------------------------

### transitionTo($state, $customProperties = [], $responsible = null)

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/State.md

Transitions the model to a new state, delegating to the state machine. Throws TransitionNotAllowedException or ValidationException on invalid transitions.

```APIDOC
## transitionTo($state, $customProperties = [], $responsible = null)

### Description
Transitions the model to the given target state, optionally storing custom properties and specifying the responsible actor. Delegates to the underlying state machine's transitionTo method, automatically deriving the current state as the 'from' state.

### Method
POST

### Endpoint
State::transitionTo

### Parameters
#### Path Parameters
- **$state** (string) - Required - Target state

#### Query Parameters
- **$customProperties** (array) - Optional - Custom data stored on the history record
- **$responsible** (mixed) - Optional - Actor; defaults to `auth()->user()`

### Request Example
```php
$salesOrder->status()->transitionTo('approved');
```

### Response
#### Success Response (200)
No explicit response body documented.

#### Response Example
No explicit response example provided.

### Error Handling
Throws TransitionNotAllowedException or ValidationException identically to StateMachine::transitionTo().
```

```APIDOC
## [METHOD] [ENDPOINT]

### Description
[Brief description of what this endpoint does]

### Method
[HTTP method: GET, POST, PUT, DELETE, etc.]

### Endpoint
[Full endpoint path with any path parameters]

### Parameters
#### Path Parameters
- **param1** (type) - Required/Optional - Description

#### Query Parameters
- **param1** (type) - Required/Optional - Description

#### Request Body
- **field1** (type) - Required/Optional - Description

### Request Example
{
  "example": "request body"
}

### Response
#### Success Response (200)
- **field1** (type) - Description

#### Response Example
{
  "example": "response body"
},
```

--------------------------------

### Query Models with whereHasStatus / whereHasFulfillment

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/README.md

Queries models with state machine constraints like withTransition(), withResponsible(), and transitionedTo() via whereHasStatus and whereHasFulfillment. Parameters can be status names or arrays.

```php
SalesOrder::with()
    ->whereHasStatus(function ($query) {
        $query
            ->withTransition('pending', 'approved')
            ->withResponsible(auth()->id())
        ;
    })
    ->whereHasFulfillment(function ($query) {
        $query
            ->transitionedTo('complete')
        ;
    })
    ->get();
```

--------------------------------

### transitions() : array

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/StateMachine.md

Abstract method that must be implemented by subclasses. Returns the transition map defining allowed state transitions.

```APIDOC
## transitions() : array

### Description
Returns the transition map: `'from' => ['to', 'to', ...]`. The special key/value `'*'` acts as a wildcard for "any state".

### Method
`transitions()`

### Signature
```php
abstract public function transitions() : array;
```

### Parameters
None.

### Return Value
- **array** - The transition map.

### Example
```php
public function transitions(): array
{
    return [
        'pending' => ['approved', 'waiting'],
        'approved' => ['processed'],
        'waiting' => ['cancelled'],
    ];
}
```
```

--------------------------------

### changed_attributes array structure

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/types.md

Example of the array structure returned by HasStateMachines::getChangedAttributes() and stored in the changed_attributes cast on StateHistory. Each key is a dirty attribute name, with 'new' and 'old' values captured at transition time.

```php
// map: attribute name => ['new' => current value, 'old' => original value]
[
    'total'  => ['new' => 200, 'old' => 100],
    'status' => ['new' => 'approved', 'old' => 'pending'],
]
```

--------------------------------

### TransitionNotAllowedException

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/errors.md

Documentation for the TransitionNotAllowedException exception, including its class, triggers, and how to catch it.

```APIDOC
## TransitionNotAllowedException

### Description
Exception thrown when a state transition is not allowed. It is thrown by `StateMachine::transitionTo()` and `StateMachine::postponeTransitionTo()` when the target state is not reachable from the current state.

### Class
`Asantibanez\LaravelEloquentStateMachines\Exceptions\TransitionNotAllowedException`

### Extends
`\Exception`

### HTTP-style code
`422`

### Message
`Transition from '{from}' to '{to}' is not allowed for model '{model}'`

### Trigger 1 — `StateMachine::transitionTo()`

Location: `src/StateMachines/StateMachine.php` L104 (permission check inside `transitionTo()`).

Condition: the target is not reachable from the current state. The check passes when any of these four lookups is true — otherwise the exception is thrown:

- `canBe($from, $to)` — `$to` is in `transitions()[$from]`
- `canBe($from, '*')` — the `$from` entry allows the `'*'` wildcard target
- `canBe('*', $to)` — the `'*'` source entry allows `$to`
- `canBe('*', '*')` — the any-to-any wildcard

The `$from` passed when going through the `State` facade is the current state; when invoking `StateMachine` directly it is whatever was supplied.

Reachable through: `State::transitionTo()`, `PendingTransitionExecutor::handle()` (via `transitionTo`).

### Trigger 2 — `StateMachine::postponeTransitionTo()`

Location: `src/StateMachines/StateMachine.php` L158.

Condition: `canBe($from, $to)` fails. **Note the asymmetry** — the postponed check consults only the exact map entry, not the `'*'` wildcard branches, so transitions permitted by wildcards may still throw here.

Reachable through: `State::postponeTransitionTo()`.

### Catching it

```php
use Asantibanez\LaravelEloquentStateMachines\Exceptions\TransitionNotAllowedException;

try {
    $salesOrder->status()->transitionTo('declined');
    $salesOrder->status()->postponeTransitionTo('invalid', Carbon::tomorrow());
} catch (TransitionNotAllowedException $e) {
    $e->getFrom();   // 'pending'
    $e->getTo();     // 'declined'
    $e->getModel();  // 'App\Models\SalesOrder' (class-string passed at throw time)
    $e->getCode();   // 422
}
```

Because it extends `\Exception`, it is also caught by generic `catch (Throwable $e)` handlers (as demonstrated by the package's own tests). Note `getModel()` returns the model **class string** (`get_class($this->model)`), not the model instance.
```

--------------------------------

### Catching TransitionNotAllowedException

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/Exceptions.md

Shows how to catch the exception when a transition is not allowed, and access the from, to, model, code, and message properties.

```php
use Asantibanez\LaravelEloquentStateMachines\Exceptions\TransitionNotAllowedException;

try {
    $salesOrder->status()->transitionTo('declined');
} catch (TransitionNotAllowedException $e) {
    $e->getFrom();   // 'pending'
    $e->getTo();     // 'declined'
    $e->getModel();  // 'App\Models\SalesOrder'
    $e->getCode();   // 422
    $e->getMessage(); // "Transition from 'pending' to 'declined' is not allowed for model 'App\Models\SalesOrder'"
}
```

--------------------------------

### Filter History with from(), to(), withCustomProperty()

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/README.md

Chains scopes on the history() relationship to filter transitions by from/to states and custom properties.

```php
$salesOrder->status()->history()
    ->from('pending')
    ->to('approved')
    ->withCustomProperty('comments', 'like', '%good%')
    ->get();
```

--------------------------------

### stateMachine()

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/State.md

Returns the underlying StateMachine instance.

```APIDOC
## stateMachine()

### Description
Returns the underlying StateMachine instance. Useful to reach recordHistory(), transitions(), defaultState() etc.

### Method
stateMachine

### Returns
- `StateMachine` - The bound machine instance
```

--------------------------------

### StateMachine::__construct($field, &$model)

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/StateMachine.md

Constructor for the StateMachine class. Sets the public properties $field and $model. Usually not called directly; model macros handle instantiation.

```APIDOC
## StateMachine::__construct($field, &$model)

### Description
Constructor for the StateMachine class. Sets the public properties `$field` and `$model`. Usually you never construct this class directly; the model macros do it.

### Method
Constructor

### Signature
```php
public function __construct($field, &$model)
```

### Parameters
- **$field** (string) - Required - Name of the model attribute controlled by this machine
- **$model** (\Illuminate\Database\Eloquent\Model, by reference) - Required - The bound Eloquent model instance

### Return Value
No return value.

### Public Properties Set
- **$field** (string) - Field name controlled by the machine
- **$model** (\Illuminate\Database\Eloquent\Model) - Bound model instance (stored by reference handed to the constructor)
```

--------------------------------

### transitions() wildcard syntax

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/types.md

Wildcard syntax supported by transitionTo() since v5.2.0. The literal '*' as a source key means any state, and as a target value means any target state. This shape is also accepted by canBe() and postponeTransitionTo().

```php
[
    '*' => ['approved', 'declined'], // from ANY state to 'approved' or 'declined'
    'approved' => '*',               // from 'approved' to ANY state
    '*' => '*',                      // from ANY to ANY
]
```

--------------------------------

### State::__construct

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/State.md

Constructor for the State class. Initializes the current state value and the bound StateMachine instance.

```APIDOC
## State::__construct

### Description
Initializes a new State instance with the current state value and the controlling StateMachine.

### Method
__construct

### Parameters
- `$state` (string|null) - Required - Current state value
- `$stateMachine` (StateMachine) - Required - The machine controlling the field

### Returns
void
```

--------------------------------

### recordHistory() abstract method

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/StateMachine.md

Required abstract method that must be implemented by subclasses. Returns true to record every transition and the initial state into the state_histories table, or false to disable history persistence.

```php
abstract public function recordHistory() : bool;
```

--------------------------------

### beforeTransitionHooks() and afterTransitionHooks() return shapes

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/types.md

Shows the return shapes for beforeTransitionHooks() and afterTransitionHooks(). beforeTransitionHooks() is keyed by $from state and callables receive ($to, $model); afterTransitionHooks() is keyed by $to state and callables receive ($from, $model).

```php
// beforeTransitionHooks(): keyed by $from state; callables receive ($to, $model)
[
    'pending' => [
        function ($to, $model) { /* ... */ },
        function ($to, $model) { /* ... */ },
    ],
]

// afterTransitionHooks(): keyed by $to state; callables receive ($from, $model)
[
    'processed' => [
        function ($from, $model) { /* ... */ },
    ],
]
```

--------------------------------

### postponeTransitionTo($from, $to, Carbon $when, $customProperties = [], $responsible = null) : ?PendingTransition

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/StateMachine.md

Schedules a state transition to be executed at a specified future time. Returns a PendingTransition model or null if the target state is the current state. Throws TransitionNotAllowedException if the transition is not allowed.

```APIDOC
## postponeTransitionTo($from, $to, Carbon $when, $customProperties = [], $responsible = null) : ?PendingTransition

### Description
Schedules a state transition to be executed at a specified future time. Returns a PendingTransition model or null if the target state is the current state. Throws TransitionNotAllowedException if the transition is not allowed.

### Method
postponeTransitionTo

### Signature
```php
public function postponeTransitionTo($from, $to, Carbon $when, $customProperties = [], $responsible = null) : ?PendingTransition
```

### Parameters
- **$from** (string|null) - Required - Starting state assumed at execution time
- **$to** (string) - Required - Target state
- **$when** (\Carbon\Carbon) - Required - When the transition should run
- **$customProperties** (array) - Optional - Key/value data stored on the pending record. Default: `[]`
- **$responsible** (mixed) - Optional - Falls back to `auth()->user()`. Default: `null`

### Behavior
1. Returns `null` immediately if `$to === $this->currentState()`.
2. Throws `TransitionNotAllowedException` if `!$this->canBe($from, $to)` — note this checks **only** the direct map entry, not the `'*'` wildcard branches that `transitionTo()` also tries.
3. `$responsible = $responsible ?? auth()->user();`
4. Delegates to `$this->model->recordPendingTransition($this->field, $from, $to, $when, $customProperties, $responsible)`.

### Returns
Returns the created `PendingTransition` model, or `null` when postponing to the current state. No validation and no hooks run at scheduling time.

### Example
```php
$pending = $salesOrder->status()->postponeTransitionTo(
    'approved',
    Carbon::now()->addDay(),
    ['comments' => 'Auto-approve tomorrow'],
    $responsible = auth()->user(),
     // → PendingTransition|null
);
```

### Error Handling
Disallowed postponed transition:
```php
try {
    $salesOrder->status()->postponeTransitionTo('invalid', Carbon::tomorrow());
} catch (TransitionNotAllowedException $e) {
    // $e->getFrom() === 'pending', $e->getTo() === 'invalid'
}
```
```

--------------------------------

### allCustomProperties()

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/StateHistory.md

Returns all custom properties of the record as an array.

```APIDOC
## allCustomProperties()

### Description
Returns all custom properties of the record as an array.

### Method
`allCustomProperties()`

### Returns
`$this->custom_properties ?? []` - An array of all custom properties.
```

--------------------------------

### postponeTransitionTo method signature

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/StateMachine.md

Method signature for postponing a state transition. Returns null if the target state equals the current state, throws TransitionNotAllowedException if the direct map entry does not allow the transition, and delegates to recordPendingTransition on the model.

```php
public function postponeTransitionTo($from, $to, Carbon $when, $customProperties = [], $responsible = null) : ?PendingTransition
```

--------------------------------

### State constructor signature

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/State.md

Constructor for the State class. Accepts the current state value and the controlling StateMachine instance, then stores them in $this->state and $this->stateMachine.

```php
public function __construct($state, $stateMachine)
```

--------------------------------

### Check Available Transitions with canBe

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/README.md

Checks whether the current state can transition to 'approved' or 'declined' using the canBe method.

```php
$salesOrder->status()->canBe('approved');

$salesOrder->status()->canBe('declined');
```

--------------------------------

### state()

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/State.md

Returns the current state value.

```APIDOC
## state()

### Description
Returns the current state value.

### Method
state

### Returns
- `string|null` - The current state value
```

--------------------------------

### allCustomProperties method signature

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/StateHistory.md

Signature for the allCustomProperties method. Returns all custom properties as an array.

```php
public function allCustomProperties()
```

--------------------------------

### transitionTo method signature

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/State.md

Declares the transitionTo method signature with parameters for target state, custom properties, and responsible actor. The method delegates to the state machine and throws TransitionNotAllowedException or ValidationException on failure.

```php
public function transitionTo($state, $customProperties = [], $responsible = null)
```

--------------------------------

### defaultState() : ?string

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/StateMachine.md

Abstract method that must be implemented by subclasses. Returns the default state assigned to the field when a model is created without an explicit value.

```APIDOC
## defaultState() : ?string

### Description
Returns the state assigned to the field when a model is created without an explicit value (used by `HasStateMachines::initStateMachines()`), or `null` for no default.

### Method
`defaultState()`

### Signature
```php
abstract public function defaultState() : ?string;
```

### Parameters
None.

### Return Value
- **?string** - The default state, or `null` if none.
```

--------------------------------

### StateHistory model configuration (guarded and casts)

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/StateHistory.md

Sets $guarded to an empty array for mass assignment and casts the JSON columns custom_properties and changed_attributes to arrays.

```php
protected $guarded = [];

protected $casts = [
    'custom_properties' => 'array',
    'changed_attributes' => 'array',
];
```

--------------------------------

### Add custom hooks with beforeTransitionHooks() and afterTransitionHooks()

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/README.md

Overrides beforeTransitionHooks() and afterTransitionHooks() to add custom callbacks. The before hooks must be keyed by the $from state (here 'approved'), and after hooks by the $to state (here 'processed'). Each key maps to an array of closures that receive ($to, $model) or ($from, $model).

```php
class StatusStateMachine extends StateMachine
{
    public function beforeTransitionHooks(): array
    {
        return [
            'approved' => [
                function ($to, $model) {
                    // Dispatch some job BEFORE "approved changes to $to"
                },
                function ($to, $model) {
                    // Send mail BEFORE "approved changes to $to"
                },
            ],
        ];
    }

    public function afterTransitionHooks(): array
    {
        return [
            'processed' => [
                function ($from, $model) {
                    // Dispatch some job AFTER "$from transitioned to processed"
                },
                function ($from, $model) {
                    // Send mail AFTER "$from transitioned to processed"
                },
            ],
        ];
    }
}
```

--------------------------------

### transitions() return shape with null key

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/types.md

Return shape of StateMachine::transitions() : array. Maps source states (including null for unset) to arrays of allowed target states. This is the contract implemented by every machine and is accepted by canBe(), transitionTo(), and postponeTransitionTo().

```php
// map: from state (string|null) => list of allowed target states (string)
[
    'pending'  => ['approved', 'declined'],   // from 'pending' to any of these
    'approved' => ['processed'],
    null       => ['pending'],                // 'null' is a valid key: transition from unset state
]
```

--------------------------------

### Query models with status history constraints

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/StateHistory.md

Query models that have a status history transition from 'pending' or 'waiting' to 'approved' and where the responsible user is the authenticated user. Uses the `whereHasStatus` macro to filter on the status history relationship.

```php
SalesOrder::with([])
    ->whereHasStatus(function ($query) {
        $query->withTransition(['pending', 'waiting'], ['approved'])
            ->withResponsible(auth()->user());
    })
    ->get();
```

--------------------------------

### defaultState() abstract method

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/StateMachine.md

Required abstract method that must be implemented by subclasses. Returns the state assigned to the field when a model is created without an explicit value, or null for no default.

```php
abstract public function defaultState() : ?string;
```

--------------------------------

### recordHistory() : bool

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/StateMachine.md

Abstract method that must be implemented by subclasses. Determines whether transition history is recorded.

```APIDOC
## recordHistory() : bool

### Description
Returns `true` to record every transition (and the initial state on model creation) into the `state_histories` table; `false` disables persistence of history.

### Method
`recordHistory()`

### Signature
```php
abstract public function recordHistory() : bool;
```

### Parameters
None.

### Return Value
- **bool** - `true` to record history, `false` to disable.
```

--------------------------------

### $model->{field}() and $model->{camelCaseField}() — field facade macros

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/HasStateMachines.md

Invoking a method whose name matches a key of $stateMachines returns a State facade capturing the current field value. Both snake_case and camelCase variants are registered.

```APIDOC
## $model->{field}() and $model->{camelCaseField}() — field facade macros

### Description
Invoking a method whose name matches a key of `$stateMachines` returns a `State` facade capturing the current field value. Both snake_case and camelCase variants are registered.

### Method
Dynamic method call

### Endpoint
`$model->{field}()` or `$model->{camelCaseField}()`

### Parameters
- **field** (string) - Required - The name of the state machine field as defined in `$stateMachines`.

### Returns
- **State** - A `State` instance representing the current field value.

### Example
```php
$salesOrder->status()->is('pending');          // bool
$salesOrder->status()->transitionTo('approved');
$salesOrder->fulfillment_status()->canBe('pending');
```
```

--------------------------------

### beforeTransitionHooks() : array

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/StateMachine.md

Optional hook method that can be overridden to return callables to run before a transition is applied.

```APIDOC
## beforeTransitionHooks() : array

### Description
Returns `[]` by default. Override to return an array keyed by **`$from` state** whose values are arrays of callables. Each callable receives `($to, $this->model)` and runs after validation but before the field value is changed/saved.

### Method
`beforeTransitionHooks()`

### Signature
```php
public function beforeTransitionHooks() : array {
```

### Parameters
None.

### Return Value
- **array** - An array keyed by `$from` state, values are arrays of callables.

### Example
```php
public function beforeTransitionHooks(): array
{
    return [
        'pending' => [
            function($to, $model) {
                $model->total = 100;
            },
            function($to, $model) {
                BeforeTransitionJob::dispatch();
            }
        ]
    ];
}
```
```

--------------------------------

### PendingTransitionsDispatcher handle() method

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/PendingTransitionsDispatcher.md

Queue job that releases all due, not-yet-applied pending transitions. It queries PendingTransition rows with notApplied() and onScheduleOrOverdue(), eager-loads the model morph relation, and for each row dispatches a PendingTransitionExecutor job and marks the row as applied by setting applied_at to now() and saving. No return value.

```php
class PendingTransitionsDispatcher implements ShouldQueue
{
    use InteractsWithQueue, Queueable, Dispatchable, SerializesModels;

    public function handle()
    {
        PendingTransition::with(['model'])
            ->notApplied()
            ->onScheduleOrOverdue()
            ->get()
            ->each(function (PendingTransition $pendingTransition) {
                PendingTransitionExecutor::dispatch($pendingTransition);

                $pendingTransition->applied_at = now();
                $pendingTransition->save();
            });
    }
}
```

--------------------------------

### MakeStateMachine class definition

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/MakeStateMachine.md

Defines the artisan generator command with signature make:state-machine {name}. Extends GeneratorCommand, so it inherits Laravel's name validation, stub replacement, file creation, success output, and the --force option. The default namespace appends \StateMachines to the root namespace.

```php
class MakeStateMachine extends GeneratorCommand
{
    protected $signature = 'make:state-machine {name}';

    protected $description = 'Create a new state machine';

    protected $type = 'StateMachine';

    protected function getStub()
    {
        return __DIR__ . '/stubs/StateMachine.php.stub';
    }

    protected function getDefaultNamespace($rootNamespace)
    {
        return $rootNamespace . '\StateMachines';
    }
}
```

--------------------------------

### snapshotsWhen($state)

Source: https://github.com/asantibanez/laravel-eloquent-state-machines/blob/master/_autodocs/api-reference/State.md

Returns all history records for the given state.

```APIDOC
## snapshotsWhen($state)

### Description
Returns all history records for the given state.

### Method
snapshotsWhen

### Parameters
#### Parameters
- **$state** (mixed) - Required - State to look up

### Returns
Collection — all history records for `$state`.
```
Tokens:
Raw