Laravel Model States

https://github.com/spatie/laravel-model-states
Admin
Laravel Model States is a package that adds state support to Eloquent models by combining state...
Tokens:7,551
Snippets:119
Trust Score:10
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Example of Transitionable State Instances Output

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/working-with-transitions/04-retrieving-transitionable-states.md

Shows the structure of the output when retrieving state instances, highlighting that these are actual objects.

```php
[
    0 => Paid {
        // State instance with model reference
    }
]
```

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

### Create a Payment Model

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/working-with-states/02-serializing-states.md

Example of creating a new payment model instance. Assumes a default state is configured.

```php
<?php

$payment = Payment::create();
?>
```

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

### Install spatie/laravel-model-states via Composer

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/04-installation-setup.md

Use this command to add the package to your Laravel project.

```bash
composer require spatie/laravel-model-states
```

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

### Example of Transitionable States Output

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/working-with-transitions/04-retrieving-transitionable-states.md

Illustrates the expected output when retrieving transitionable states, showing a simple array of state names.

```php
[
    0 => "paid"
]
```

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

### Create Payment with Custom State

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/working-with-states/02-serializing-states.md

Example of creating a payment model and explicitly setting its state using the class name, which will be serialized using its custom name.

```php
<?php

$payment = Payment::create([
    'state' => Paid::class,
]);
?>
```

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

### Define State Transitions Configuration

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/working-with-transitions/04-retrieving-transitionable-states.md

Configure allowed transitions between states within your State class. This setup is crucial for defining the valid state flow of your model.

```php
abstract class PaymentState extends State
{
    // …

    public static function config(): StateConfig
    {
        return parent::config()
            ->allowTransition(Pending::class, Paid::class)
            ->allowTransition(Paid::class, Refunded::class);
    }
}
```

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

### Retrieve Transitionable States

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/working-with-transitions/04-retrieving-transitionable-states.md

Get an array of string representations for all states that the current state can transition to. Useful for displaying available options.

```php
$transitionableStates = $payment->state->transitionableStates();
```

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

### Retrieve Transitionable States Count

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/working-with-transitions/04-retrieving-transitionable-states.md

Get the number of available transitions from the current state. This is a simple integer count.

```php
$stateCount = $payment->state->transitionableStatesCount(); // 4
```

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

### Get Registered States for Specific Column

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/working-with-states/03-listing-states.md

Retrieve all registered state classes for a specific column of a model. This method returns a collection of state class names.

```php
[
    'declined',
    'paid',
    'pending',
],
```

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

### Get All Default States for Model

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/working-with-states/03-listing-states.md

Retrieve all default states for a model, keyed by column. This method returns a collection where keys are column names and values are the default state class names or null if no default is set.

```php
[
    "state" => 'App\States\Invoice\Pending',
    "fulfillment" => null,
]
```

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

### Get All Registered States for Model

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/working-with-states/03-listing-states.md

Retrieve all registered state morph names for a model, grouped by column. This method returns a collection where keys are column names and values are arrays of state names.

```php
[ 
    "state" => [
        'declined',
        'paid',
        'pending',
    ],
    "fulfillment" => [
        'complete',
        'partial',
        'unfulfilled',
    ]
]
```

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

### Get Default State for Specific Column

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/working-with-states/03-listing-states.md

Retrieve the default state class for a specific column of a model. This method returns the default state class name or null if no default is set.

```php
'App\States\Invoice\Pending'
```

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

### Publish the configuration file

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/04-installation-setup.md

Run this Artisan command to publish the package's configuration file. This step is optional.

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

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

### Transitioning Model State and Accessing State Behavior

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/01-introduction.md

Retrieve a model instance, transition its state using `transitionTo`, and access state-specific methods like `color`.

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

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

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

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

### Define a Custom Transition Class

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/working-with-transitions/02-custom-transition-classes.md

Create a class extending `Spatie\ModelStates\Transition` to encapsulate logic for a specific state change. The constructor can accept model and other custom arguments, which are passed from the `transitionTo` method. The `handle` method contains the core logic to be executed.

```php
use Spatie\ModelStates\Transition;

class PendingToFailed extends Transition
{
    private Payment $payment;

    private string $message;

    public function __construct(Payment $payment, string $message)
    {
        $this->payment = $payment;

        $this->message = $message;
    }

    public function handle(): Payment
    {
        $this->payment->state = new Failed($this->payment);
        $this->payment->failed_at = now();
        $this->payment->error_message = $this->message;

        $this->payment->save();

        return $this->payment;
    }
}
```

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

### Configure Simple and Custom Transitions

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/working-with-transitions/01-configuring-transitions.md

Use `allowTransition` to define allowed state changes, optionally specifying a custom transition class for complex logic.

```php
abstract class PaymentState extends State
{
    // …

    public static function config(): StateConfig
    {
        return parent::config()
            ->allowTransition(Pending::class, Paid::class)
            ->allowTransition(Pending::class, Failed::class, PendingToFailed::class);
    }
}
```

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

### Trigger Transition with Arguments

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/working-with-transitions/02-custom-transition-classes.md

Use the `transitionTo` method on the model's state to initiate a transition. Any arguments passed after the target state class will be forwarded to the transition class's constructor, after the model instance itself.

```php
$payment->state->transitionTo(Failed::class, 'error message');
```

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

### Run Tests

Source: https://github.com/spatie/laravel-model-states/blob/main/README.md

Execute the package's test suite using Composer. This command ensures that the package is functioning correctly and helps in development.

```bash
composer test
```

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

### Automatically Register All Transitions

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/working-with-transitions/01-configuring-transitions.md

Employ `allowAllTransitions` to permit transitions between any registered states within the same directory as the abstract state class.

```php
abstract class PaymentState extends State
{
    // …

    public static function config(): StateConfig
    {
        return parent::config()
            ->allowAllTransitions();
    }
}
```

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

### Define State UI and Logic Methods

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/working-with-transitions/04-retrieving-transitionable-states.md

Implement abstract methods in your base State class and provide concrete implementations in specific state classes to encapsulate UI-related logic like color, label, and icon.

```php
abstract class PaymentState extends State
{
    abstract public function color(): string;
    abstract public function label(): string;
    abstract public function icon(): string;

    // ...other state methods
}

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

    public function label(): string
    {
        return 'Mark as Paid';
    }

    public function icon(): string
    {
        return 'check-circle';
    }
}
```

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

### Configure States with PHP 8 Attributes

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/working-with-states/01-configuring-states.md

Use attributes to define allowed transitions, default states, and register state classes for your model states. Requires PHP 8 or higher.

```php
use Spatie\ModelStates\Attributes\AllowTransition;
use Spatie\ModelStates\Attributes\RegisterState;
use Spatie\ModelStates\State;

#[ 
    AllowTransition(Pending::class, Paid::class),
    AllowTransition(Pending::class, Failed::class),
    DefaultState(Pending::class),
    RegisterState(Cancelled::class),
    RegisterState([ExampleOne::class, ExampleTwo::class]),
]
abstract class PaymentState extends State
{
    abstract public function color(): string;
}
```

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

### Transition to a Specific State

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/working-with-transitions/01-configuring-transitions.md

Initiate a state transition by calling the `transitionTo` method on the state field, passing the target state class.

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

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

### Registering States from Custom Directories

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/working-with-states/01-configuring-states.md

Utilize `registerStatesFromDirectory` in the `config` method to automatically discover and register all state classes within specified directories, simplifying manual registration.

```php
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)
            ->registerStatesFromDirectory(app_path('States/Payment'))
            ->registerStatesFromDirectory(
                __DIR__ . '/States',
                __DIR__ . '/MoreStates',
                // add as many directories as you need
            );
    }
}
```

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

### Default configuration file content

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/04-installation-setup.md

This is the default content of the configuration file. It specifies the default transition class.

```php
return [

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

];
```

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

### Allow Multiple Transitions at Once

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/working-with-transitions/01-configuring-transitions.md

Utilize the `allowTransitions` shorthand to define multiple allowed transitions in a single configuration call.

```php
abstract class PaymentState extends State
{
    // …

    public static function config(): StateConfig
    {
        return parent::config()
            ->allowTransitions([
                [Pending::class, Paid::class],
                [Pending::class, Failed::class, PendingToFailed::class],
            ]);
    }
}
```

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

### Retrieve Transitionable State Instances

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/working-with-transitions/04-retrieving-transitionable-states.md

Obtain an array of actual state objects that the current state can transition to. This allows access to state-specific methods and properties.

```php
$stateInstances = $payment->state->transitionableStateInstances();
```

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

### Abstract Payment State Class Configuration

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/01-introduction.md

Define an abstract state class that extends `Spatie\ModelStates\State`. Configure default states and allowed transitions using `StateConfig`.

```php
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)
        ;
    }
}
```

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

### Manually Trigger Transition with Transition Class

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/working-with-transitions/02-custom-transition-classes.md

Alternatively, you can instantiate and pass a transition class directly to the `transition` method. This approach can be beneficial for IDE autocompletion and when you need more explicit control over the transition object.

```php
$payment->state->transition(new CreatedToFailed($payment, 'error message'));
```

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

### Inject Dependencies in Transition Handle Method

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/working-with-transitions/03-dependency-injection-in-transition-classes.md

Inject dependencies directly into the `handle` method of a transition class. The dependency will be resolved from the service container.

```php
class TransitionWithDependency extends Transition
{
    // …

    public function handle(Dependency $dependency)
    {
        // $dependency is resolved from the container
    }
}
```

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

### Implement State Change Listener with Custom Parameter

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/working-with-transitions/06-custom-default-transition-class.md

Implement the `handle` method in your state change listener to access custom parameters passed during the transition. The `silent` parameter controls whether user notifications are sent.

```php
use Spatie\ModelStates\Events\StateChanged;

class OrderStateChangedListener
{
    public function handle(StateChanged $event): void
    {
        $isSilent = $event->transition->silent;

        $this->processOrderState($event->model);

        if (! $isSilent) {
            $this->notifyUser($event->model);
        }
    }
}
```

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

### Manually Registering Concrete States

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/working-with-states/01-configuring-states.md

Use the `registerState` method within the `config` method to manually register concrete state classes, especially if they are located in custom directories.

```php
use Spatie\ModelStates\State;
use Spatie\ModelStates\StateConfig;

use Your\Concrete\State\Class\Cancelled; // this may be wherever you want
use Your\Concrete\State\Class\ExampleOne;
use Your\Concrete\State\Class\ExampleTwo;

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)
            ->registerState(Cancelled::class)
            ->registerState([ExampleOne::class, ExampleTwo::class])
        ;
    }
}
```

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

### Check for Available Transitions

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/working-with-transitions/04-retrieving-transitionable-states.md

Determine if there are any transitions possible from the current state. Returns a boolean value.

```php
$hasTransitions = $payment->state->hasTransitionableStates(); // true or false
```

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

### Transition with Custom Parameter to Omit Notification

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/working-with-transitions/06-custom-default-transition-class.md

Use the `transitionTo` method with a custom parameter (e.g., `true` for silent) to control specific behaviors like omitting notifications. Custom parameters are only available within event listeners.

```php
class OrderService {
    public function markAsPaid(Order $order): void
    {
        // Will trigger notification
        $order->state->transitionTo(PaidState::class);
        // Also can be specified explicitly
        $order->state->transitionTo(PaidState::class, false);
    }

    public function markAsPaidSilently(Order $order): void
    {
        // Will not trigger notification
        $order->state->transitionTo(PaidState::class, true);
    }
}
```

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

### Concrete Paid State Implementation

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/01-introduction.md

Implement a concrete state class by extending the abstract state class and defining specific behaviors, such as the `color` method.

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

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

### Ignore Same State Transitions

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/working-with-transitions/01-configuring-transitions.md

Use `ignoreSameState` to allow transitions to the current state without explicit configuration. The `StateChanged` event will still fire.

```php
abstract class PaymentState extends State
{
    // …

    public static function config(): StateConfig
    {
        return parent::config()
            ->ignoreSameState()
            ->allowTransition([Created::class, Pending::class], Failed::class, ToFailed::class);
    }
}
```

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

### Abstract State Class Definition

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/working-with-states/01-configuring-states.md

Create an abstract state class that extends `Spatie\ModelStates\State`. This class serves as a blueprint for all concrete states and can define common methods like `color()`.

```php
use Spatie\ModelStates\State;

/**
 * @extends State<\App\Models\Payment>
 */
abstract class PaymentState extends State
{
    abstract public function color(): string;
}
```

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

### Configure Allowed Transitions in State

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/working-with-transitions/02-custom-transition-classes.md

Register custom transitions within your state configuration using `allowTransition`. This method maps a source state, a target state, and the custom transition class that will handle the transition.

```php
abstract class PaymentState extends State
{
    // …

    public static function config(): StateConfig
    {
        return parent::config()
            ->allowTransition(Pending::class, Failed::class, PendingToFailed::class);
    }
}
```

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

### Display Transitions in Blade

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/working-with-transitions/04-retrieving-transitionable-states.md

Iterate through transitionable state instances in a Blade view to display dynamic UI elements like labels, colors, and icons based on state properties.

```blade
@foreach($payment->state->transitionableStateInstances() as $stateInstance)
    <div>
        <span style="color: {{ $stateInstance->color() }}">{{ $stateInstance->label() }}</span>
        <i class="{{ $stateInstance->icon() }}"></i>
    </div>
@endforeach
```

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

### Allow Multiple From States for One To State

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/working-with-transitions/01-configuring-transitions.md

Configure a single `allowTransition` call to permit transitions from multiple source states to a single destination state.

```php
abstract class PaymentState extends State
{
    // …

    public static function config(): StateConfig
    {
        return parent::config()
            ->allowTransition([Created::class, Pending::class], Failed::class, ToFailed::class);
    }
}
```

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

### Define Payment Model with State Support

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/01-introduction.md

Use the `HasStates` trait to enable state management for your Eloquent model. Ensure the state attribute is cast to the appropriate state class.

```php
use Spatie\ModelStates\HasStates;

class Payment extends Model
{
    use HasStates;

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

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

### Implement Transition Guard

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/working-with-transitions/02-custom-transition-classes.md

Add a `canTransition` method to your custom transition class to implement conditional logic. If this method returns `false`, the transition will be aborted, and a `TransitionNotAllowed` exception will be thrown.

```php
class CreatedToFailed extends Transition
{
    // …

    public function canTransition(): bool
    {
        return $this->payment->state->equals(Created::class);
    
    }
}
```

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

### Create Custom Default Transition Class

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/working-with-transitions/06-custom-default-transition-class.md

Extend `DefaultTransition` to add custom properties like `silent` to your transitions. This class is used when you need to pass additional data to all state changes.

```php
use Spatie\ModelStates\DefaultTransition;
use Spatie\ModelStates\State;

class CustomDefaultTransitionWithAttributes extends DefaultTransition
{
    public function __construct($model, string $field, State $newState, public bool $silent = false)
    {
        parent::__construct($model, $field, $newState);
    }
}
```

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

### Implement HasStatesContract for Type-Hinting

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/working-with-states/01-configuring-states.md

Implement the HasStatesContract interface and use the HasStates trait to ensure your model always works with state objects, improving type-hinting.

```php
use Spatie\ModelStates\HasStates;
use Spatie\ModelStates\HasStatesContract;

class Payment extends Model implements HasStatesContract
{
    use HasStates;

    // …
}
```

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

### Ignore Same State Transition Attribute

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/working-with-transitions/01-configuring-transitions.md

Alternatively, apply the `#[IgnoreSameState]` attribute to the abstract state class to achieve the same behavior.

```php
#[IgnoreSameState]
abstract class PaymentState extends State
{
    //...
}
```

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

### Filter by State

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/querybuilder-support/01-state-scopes.md

Use `whereState` to filter models by a single state or an array of states. Use `whereNotState` to exclude models with specific states.

```php
$payments = Payment::whereState('state', Paid::class);
$payments = Payment::whereState('state', [Pending::class, Paid::class]);
$payments = Payment::whereState('state', Pending::class)->orWhereState('state', Paid::class);
```

```php
$payments = Payment::whereNotState('state', Pending::class);
$payments = Payment::whereNotState('state', [Failed::class, Canceled::class]);
$payments = Payment::whereNotState('state', Failed::class)->orWhereNotState('state', Canceled::class);
```

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

### Database Schema for State Field

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/working-with-states/01-configuring-states.md

Define a string column in your database migration to store the state of the model. This field will be managed by the `HasStates` trait.

```php
Schema::table('payments', function (Blueprint $table) {
    $table->string('state');
});
```

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

### Check if a Specific Transition is Possible

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/working-with-transitions/04-retrieving-transitionable-states.md

Verify if the model's current state can transition to a specified target state class. Returns a boolean.

```php
$payment->state->canTransitionTo(Paid::class);
```

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

### Transitioning to State Objects in Laravel Model States

Source: https://github.com/spatie/laravel-model-states/blob/main/UPGRADING.md

In v2, states are directly accessed via their field property, simplifying transitions. This replaces the older method of passing the field name as a string.

```php
$model->canTransitionTo(StateB::class, 'status');
```

```php
$model->status->canTransitionTo(StateB::class);
```

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

### Define Custom State Name

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/working-with-states/02-serializing-states.md

Define a static $name property on a concrete state class to control its serialized representation. Avoid hyphens in custom names.

```php
<?php

class Paid extends PaymentState
{
    public static $name = 'paid';

    // …
}
?>
```

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

### Registering a Custom StateChanged Event

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/working-with-states/01-configuring-states.md

Override the default `StateChanged` event by specifying a custom event class using the `stateChangedEvent` method within the `config` configuration.

```php
use Spatie\ModelStates\State;
use Spatie\ModelStates\StateConfig;

use Your\Concrete\State\Event\CustomStateChanged;

abstract class PaymentState extends State
{
    abstract public function color(): string;
    
    public static function config(): StateConfig
    {
        return parent::config()
            ->stateChangedEvent(CustomStateChanged::class)
        ;
    }
}
```

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

### Define Invoice Model with States

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/working-with-states/03-listing-states.md

This PHP code defines an Eloquent model named Invoice that utilizes the HasStates trait and specifies state casting for 'state' and 'fulfillment' columns.

```php
namespace App;

use App\States\Invoice\InvoiceState;
use App\States\Invoice\Declined;
use App\States\Invoice\Paid;
use App\States\Invoice\Pending;
use App\States\Fulfillment\FulfillmentState;
use App\States\Fulfillment\Complete;
use App\States\Fulfillment\Partial;
use App\States\Fulfillment\Unfulfilled;
use Illuminate\Database\Eloquent\Model;
use Spatie\ModelStates\HasStates;

class Invoice extends Model
{
    use HasStates;

    protected $casts = [
        'state' => InvoiceState::class,
        'fulfillment' => FulfillmentState::class,
    ];
}
```

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

### Validate incoming request data with ValidStateRule

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/request-validation/01-state-validation-rule.md

Use ValidStateRule to ensure the 'state' field in the request data contains a valid state from the PaymentState enum. The rule can be made nullable.

```php
use Spatie\ModelStates\Validation\ValidStateRule;

request()->validate([
    'state' => new ValidStateRule(PaymentState::class),
]);
```

```php
// Allowing null
request()->validate([
    'state' => ValidStateRule::make(PaymentState::class)->nullable(),
]);
```

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

### Use HasStates Trait in Model

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/working-with-states/01-configuring-states.md

Add the `HasStates` trait to your Eloquent model to enable state management capabilities. Ensure your model has a corresponding string field in the database for the state.

```php
use Spatie\ModelStates\HasStates;

class Payment extends Model
{
    use HasStates;

    // …
}
```

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

### Filter by State with Custom Column Name

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/querybuilder-support/01-state-scopes.md

When the state column has a different name, for instance, due to a join, use the full column name with the scopes.

```php
$payments = Payment::whereState('payments.state', Paid::class);
```

```php
$payments = Payment::whereNotState('payments.state', Pending::class);
```

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

### Casting State Field in Model

Source: https://github.com/spatie/laravel-model-states/blob/main/docs/working-with-states/01-configuring-states.md

Configure the `$casts` property in your Eloquent model to associate the database state field with its corresponding abstract state class. This ensures proper serialization and deserialization.

```php
class Payment extends Model
{
    // …

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