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.