spatie/laravel-model-status

A package to enable assigning statuses to Eloquent Models

Assign statuses to Eloquent models

, _(*1)

Imagine you want to have an Eloquent model hold a status. It's easily solved by just adding a status field to that model and be done with it. But in case you need a history of status changes or need to store some extra info on why a status changed, just adding a single field won't cut it., _(*2)

This package provides a HasStatuses trait that, once installed on a model, allows you to do things like this:, _(*3)

// set a status
$model->setStatus('pending', 'needs verification');

// set another status
$model->setStatus('accepted');

// specify a reason
$model->setStatus('rejected', 'My rejection reason');

// get the current status
$model->status(); // returns an instance of \Spatie\ModelStatus\Status

// get the previous status
$latestPendingStatus = $model->latestStatus('pending');

$latestPendingStatus->reason; // returns 'needs verification'

Support us

, _(*4)

We invest a lot of resources into creating best in class open source packages. You can support us by buying one of our paid products., _(*5)

We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on our contact page. We publish all received postcards on our virtual postcard wall., _(*6)

Installation

You can install the package via composer:, _(*7)

composer require spatie/laravel-model-status

You must publish the migration with:, _(*8)

php artisan vendor:publish --provider="Spatie\ModelStatus\ModelStatusServiceProvider" --tag="migrations"

Migrate the statuses table:, _(*9)

php artisan migrate

Optionally you can publish the config-file with:, _(*10)

php artisan vendor:publish --provider="Spatie\ModelStatus\ModelStatusServiceProvider" --tag="config"

This is the contents of the file which will be published at config/model-status.php, _(*11)

return [

    /*
     * The class name of the status model that holds all statuses.
     *
     * The model must be or extend `Spatie\ModelStatus\Status`.
     */
    'status_model' => Spatie\ModelStatus\Status::class,

    /*
     * The name of the column which holds the ID of the model related to the statuses.
     *
     * You can change this value if you have set a different name in the migration for the statuses table.
     */
    'model_primary_key_attribute' => 'model_id',

];

Usage

Add the HasStatuses trait to a model you like to use statuses on., _(*12)

use Spatie\ModelStatus\HasStatuses;

class YourEloquentModel extends Model
{
    use HasStatuses;
}

Set a new status

You can set a new status like this:, _(*13)

$model->setStatus('status-name');

A reason for the status change can be passed as a second argument., _(*14)

$model->setStatus('status-name', 'optional reason');

Retrieving statuses

You can get the current status of model:, _(*15)

$model->status; // returns a string with the name of the latest status

$model->status(); // returns the latest instance of `Spatie\ModelStatus\Status`

$model->latestStatus(); // equivalent to `$model->status()`

You can also get latest status of a given name:, _(*16)

$model->latestStatus('pending'); // returns an instance of `Spatie\ModelStatus\Status` that has the name `pending`

Get all available status names for the model., _(*17)

$statusNames = $model->getStatusNames(); // returns a collection of all available status names.

The following examples will return statusses of type status 1 or status 2, whichever is latest., _(*18)

$lastStatus = $model->latestStatus(['status 1', 'status 2']);

// or alternatively...
$lastStatus = $model->latestStatus('status 1', 'status 2');

All associated statuses of a model can be retrieved like this:, _(*19)

$allStatuses = $model->statuses;

This will check if the model has status:, _(*20)

$model->setStatus('status1');

$isStatusExist = $model->hasStatus('status1'); // return true
$isStatusExist = $model->hasStatus('status2'); // return false

Retrieving models with a given latest state

The currentStatus scope will return models that have a status with the given name., _(*21)

$allPendingModels = Model::currentStatus('pending');

//or array of statuses
$allPendingModels = Model::currentStatus(['pending', 'initiated']);
$allPendingModels = Model::currentStatus('pending', 'initiated');

Retrieving models without a given state

The otherCurrentStatus scope will return all models that do not have a status with the given name, including any model that does not have any statuses associated with them., _(*22)

$allNonPendingModels = Model::otherCurrentStatus('pending');

You can also provide an array of status names to exclude from the query., _(*23)

$allNonInitiatedOrPendingModels = Model::otherCurrentStatus(['initiated', 'pending']);

// or alternatively...
$allNonInitiatedOrPendingModels = Model::otherCurrentStatus('initiated', 'pending');

Validating a status before setting it

You can add custom validation when setting a status by overwriting the isValidStatus method:, _(*24)

public function isValidStatus(string $name, ?string $reason = null): bool
{
    ...

    if (! $condition) {
        return false;
    }

    return true;
}

If isValidStatus returns false a Spatie\ModelStatus\Exceptions\InvalidStatus exception will be thrown., _(*25)

You may bypass validation with the forceSetStatus method:, _(*26)

$model->forceSetStatus('invalid-status-name');

Check if status has been assigned

You can check if a specific status has been set on the model at any time by using the hasEverHadStatus method:, _(*27)

$model->hasEverHadStatus('status 1');

Check if status has never been assigned

You can check if a specific status has never been set on the model at any time by using the hasNeverHadStatus method:, _(*28)

$model->hasNeverHadStatus('status 1');

Delete status from model

You can delete any given status that has been set on the model at any time by using the deleteStatus method:, _(*29)

Delete single status from model:, _(*30)

$model->deleteStatus('status 1');

Delete multiple statuses from model at once:, _(*31)

$model->deleteStatus(['status 1', 'status 2']);

Events

TheSpatie\ModelStatus\Events\StatusUpdated event will be dispatched when the status is updated., _(*32)

namespace Spatie\ModelStatus\Events;

use Illuminate\Database\Eloquent\Model;
use Spatie\ModelStatus\Status;

class StatusUpdated
{
    /** @var \Spatie\ModelStatus\Status|null */
    public $oldStatus;

    /** @var \Spatie\ModelStatus\Status */
    public $newStatus;

    /** @var \Illuminate\Database\Eloquent\Model */
    public $model;

    public function __construct(?Status $oldStatus, Status $newStatus, Model $model)
    {
        $this->oldStatus = $oldStatus;

        $this->newStatus = $newStatus;

        $this->model = $model;
    }
}

Custom model and migration

You can change the model used by specifying a class name in the status_model key of the model-status config file., _(*33)

You can change the column name used in the status table (model_id by default) when using a custom migration where you changed that. In that case, simply change the model_primary_key_attribute key of the model-status config file., _(*34)

Testing

This package contains integration tests that are powered by orchestral/testbench., _(*35)

You can run all tests with:, _(*36)

composer test

Changelog

Please see CHANGELOG for more information what has changed recently., _(*37)

Contributing

Please see CONTRIBUTING for details., _(*38)

Security

If you've found a bug regarding security please mail security@spatie.be instead of using the issue tracker., _(*39)

Credits

• Thomas Verhelst
• Freek Van der Herten
• All Contributors

License

The MIT License (MIT). Please see License File for more information., _(*40)