Laravel Eloquent Status Package

The Laravel Eloquent Status package by Rasmus Christoffer Nielsen is a package that helps you check the state and status of eloquent models without cluttering them.

I am sure many of us have built something similar to the following example: let’s say you have a post model with various statuses, such as draft, scheduled, and published. With Laravel you can easily build scopes to query these states with local query scopes:

/**
 * Scope a query to only include popular users.
 *
 * @param \Illuminate\Database\Eloquent\Builder $query
 * @return \Illuminate\Database\Eloquent\Builder
 */
public function scopePublished($query)
{
    return $query
        ->where('status', 'published')
        ->whereNotNull('published_at');
}

You might have deeply held opinions about how to accomplish this scope, but I think you get the idea. We can use a scope to get only published posts:

Post::published()->get();

You might have an additional conditional method for asserting the individual state of a post record:

/**
 * @return bool
 */
public function isPublished()
{
    return $this->status === 'published' &&
           $this->published_at !== null;
}

Enter the Eloquent status package, it might be an approach you want to use on your model statuses.

Eloquent Status Package

With the Eloquent Status package now you can use an API like this to check that status of your model:

Post::status('published')->get();

On an individual model you can check the state of your object with a checkStatus method:

$post->checkStatus('scheduled'); // true or false

For this to work, you would create a dedicated status class such as PostStatus:

use \Makeable\EloquentStatus\Status;
 
class PostStatus extends Status
{
    public function published($query)
    {
        return $query->where('status', 'published')
                     ->whereNotNull('published_at');
    }
 
    public function scheduled($query)
    {
        return $query->where('status', 'scheduled')
                     ->whereNotNull('scheduled_at');
    }
 
    // Etc...
}

Next, you define a trait on your model to support status checks:

use \Makeable\EloquentStatus\HasStatus;
 
class Post extends Eloquent
{
    use HasStatus;
}

With the trait in place, you can query the database using your PostStatus class:

Post::status(new PostStatus('published'))->get();

This technique is very close to our scoped method, but the author of the package suggests a few benefits of this approach:

• We’ve defined and encapsulated all our statuses in one place de-cluttering our model
• We can only query against valid statuses

Trying to query on an invalid status will throw an exception:

Post::status(new PostStatus('bupkis'))->get();

Next, you can use the same status definitions to check it a model instance has a given status, which is powered by another package by Rasmus called laravel-query-kit:

$post->checkStatus(new PostStatus('published')); // Bool

My favorite feature in this package is the ability to guess the model’s status:

<?php
 
use Makeable\EloquentStatus\HasStatus;
 
class Post extends Eloquent
{
    use HasStatus;
 
    public function getStatusAttribute()
    {
        return PostStatus::guess($this);
    }
}
 
// Example usage
$post->status

Learn More

Check out the package’s GitHub repo for complete installation and usage instructions. Rasmus also wrote about his package in his post An eloquent way of handling model state.