Using Eloquent Query Scopes in Laravel

Published: Dec 29, 2019 by C.S. Rhymes

If you are writing eloquent queries in your Laravel project and find yourself writing the same logic in your queries over and over again then query scopes might be of use to you. Scopes offer you a way of extracting a part of a query from your controller and into your model to simplify your queries and keep them cleaner.

Laravel has local and global scopes, but this article only discusses local scopes.

Published and Draft Posts

Lets start with a blog as the first example. For a blog you will have posts, but some posts may be published and some may be drafts. We will set a boolean flag to decide if the post is published or not, with true for published and false for draft.

$publishedPosts = Post::where('published', true)->get();

$draftPosts = Post::where('published', false)->get();

This seems simple enough, but to make this a bit more readable and easier to write we can refactor these queries by using scopes. We can add a couple of methods to our Post model that start with scope and then the name you want to use, such as scopePublished and scopeDraft so you can call published() and draft() in your eloquent queries.

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class Post extends Model
{
    public function scopePublished($query)
    {
        return $query->where('published', true);
    }

    public function scopeDraft($query)
    {
        return $query->where('published', false);
    }
}

With this in place, we can then rewrite our queries to use these new scopes, making them cleaner and easier to read.

$publishedPosts = Post::published()->get();

$draftPosts = Post::draft()->get();

Updating the published logic

This may seem a bit over the top to do this for one instance, but imagine you have multiple queries throughout your project that use this same logic. What happens if you need to change the logic of how you determine if a post is published?

For example, you want to add a published_at date time to your posts table so you can determine when the post was published as well as if its published or not. We can remove the published boolean flag and use the published_at for both the date time and to determine if the post is published.

If you don’t extract this logic to a scope in your model then you will have to update every instance in your project. With a scope you can update the logic in one place, in your model, and the rest of the queries can remain unchanged.

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class Post extends Model
{
    public function scopePublished($query)
    {
        return $query->whereNotNull('published_at');
    }

    public function scopeDraft($query)
    {
        return $query->whereNull('published_at');
    }
}

Date Mutators

As a side note, if you add a date time column to your table, such as published_at, then it is worth adding it to the $dates property of your model to convert it to an instance of Carbon. This allows you to pass in a UNIX timestamp, date string a date-time string or a DateTime/Carbon instance to the field when saving.

class Post extends Model
{
    protected $dates = ['published_at'];
}

It will also allow you to use Carbon format() method when displaying the field.

$post->published_at->format('d/m/Y');

Post Types

If we expand on our post example a little more, you may have some posts that are news and others are special offers that are displayed on different parts of your site. This way you can reuse a lot of your exisitng code to create and manage posts.

We can store this in the posts table as a string, such as news or special_offers, in the type table and then make a dynamic scope that accepts a parameter to help us filter out the posts we want.

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class Post extends Model
{
    public function scopeType($query, $type)
    {
        return $query->where('type', $type);
    }
}

We can then create a query using this scope.

$newsPosts = Post::type('news')->get();

Chaining query scopes

We now have a way of getting published posts and a way of getting news posts. With scopes, we can also chain them together in different combinations to get the posts we want, such as published news posts or draft special offer posts.

$publishedNewsPosts = Post::published()->type('news')->get();

$draftSpecialOfferPosts = Post::draft()->type('special_offers')->get();

If we had an additional type of posts, such as tutorials and wanted to get published posts for news or tutorials type then we could use the orWhere helper for this.

$posts = Post::published()->type('news')->orWhere->type('tutorials')->get();

Hopefully this will give you some ideas for how you can use query scopes in your future Laravel projects.

laravel webdev php database

Share

Latest Posts

Refactoring to Laravel 8 Class Model Factories
Refactoring to Laravel 8 Class Model Factories

Laravel 8 introduced new class based model factories and if you have an existing project you can use the legacy factories package to keep using the old factories. I have tended to keep the factories as they were and continue development, but after working on a fresh Laravel 8 project and using the new class based syntax I decided to go back and update the factories in the older Laravel apps. This article explains how I went about refactoring the factories to classes.

The PHP array
The PHP array

Arrays are a useful toolt to store multiple values. You can access a specific value in an array using a key. By default, if you don’t specify keys, they will be numeric and start at zero (not one);

Run Laravel artisan commands in PHP Storm
Run Laravel artisan commands in PHP Storm

PHP Storm has a built in terminal window which you can use to run Laravel artisan commands, but there is a quick configuration change that you can do to make it even easier to run artisan commands.

How NOT to make a website

How NOT to make a Website

By C.S. Rhymes

From £8.99

Nigel's Intranet Adventure

Nigel's Intranet Adventure

By C.S. Rhymes

From £2.69