In this post, we’ll explore how to create and use custom query scopes in Laravel to make your code more reusable, readable, and maintainable. By the end, you’ll wonder how you ever lived without them! 🛠️

What Are Query Scopes in Laravel? 🤔

Query scopes are methods on your Eloquent models that allow you to define reusable query logic. They help streamline your database interactions, especially when you find yourself writing the same query logic in multiple places.

Laravel offers two types of scopes:

1. Global Scopes: Apply to all queries on a model.
2. Local Scopes: Applied explicitly when querying.

In this guide, we’ll focus on local scopes, which are simple yet powerful tools for improving your codebase.

Why Use Custom Query Scopes? 🧐

Here are some reasons to adopt query scopes:

• Reusability: Define query logic once and use it everywhere.
• Readability: Your queries become more descriptive and easier to understand.
• Maintainability: Updating query logic is a breeze since you only modify it in one place.

Let’s dive into a practical & very simple example! 🌊

Use Case: Retrieving Published Posts

Imagine you have a blogging application with a Post model. You frequently need to fetch posts marked as "published" from your database. Instead of repeating this query logic, you can create a custom query scope.

Step 1: Define the Custom Scope

To start, add a scope method to your Post model. Laravel uses the scope prefix for query scopes.

Here’s how you define a published scope:

<?php
namespace App\Models;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
class Post extends Model
{
    use HasFactory;
    /**
     * Scope a query to only include published posts.
     *
     * @param \Illuminate\Database\Eloquent\Builder $query
     * @return \Illuminate\Database\Eloquent\Builder
     */
    public function scopePublished($query)
    {
        return $query->where('is_published', true);
    }
}

📢Pro Tip: The scope prefix is only used when defining the method. You’ll call it without the scope prefix.

Step 2: Use the Scope in Your Controller

Now, let’s see how this scope simplifies your queries. In your PostController, you can retrieve only published posts with a single method call:

<?php

namespace App\Http\Controllers;

use App\Models\Post;

class PostController extends Controller
{
    public function index()
    {
        // Fetch all published posts
        $publishedPosts = Post::published()->get();

        return view('posts.index', ['posts' => $publishedPosts]);
    }
}

Notice how clean and descriptive the query becomes! Instead of repeating the where clause every time, you simply chain the published method.

Step 3: Using the Scope in Tinker or Routes

You can also test your scope directly in Laravel Tinker or within your routes:

Testing with Tinker:

php artisan tinker

>>> App\Models\Post::published()->get();

Using in Routes:

Route::get('/published-posts', function () {
    return App\Models\Post::published()->get();
})

Step 4: Adding More Scopes

Scopes are flexible and can accept parameters. Let’s extend our Post model with another scope to filter posts by a specific author:

public function scopeByAuthor($query, $authorId)
{
    return $query->where('author_id', $authorId);
}

Now you can chain scopes for even more concise and readable queries:

$posts = Post::published()->byAuthor(1)->get();

Advantages of Using Query Scopes 🌟

Here’s a summary of why query scopes are a game-changer:

1. Cleaner Controllers: No more bloated controllers with repetitive query logic.
2. Descriptive Queries: Queries like Post::published() clearly convey intent.
3. DRY Principle: Avoid repeating yourself by centralizing query logic.
4. Easy Debugging: If something breaks, you only need to update the scope in one place.

Bonus: Global Scopes

While this article focuses on local scopes, it’s worth mentioning global scopes. These automatically apply to all queries for a model. For example, you might want to always exclude soft-deleted records from queries.

Here’s a quick example of defining a global scope:

use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Scope;

class PublishedScope implements Scope
{
    public function apply(Builder $builder, Model $model)
    {
        $builder->where('is_published', true);
    }
}

// Applying the global scope
Post::addGlobalScope(new PublishedScope);

Global scopes can be powerful but should be used sparingly, as they affect every query on the model.

Final Thoughts

Custom query scopes are an excellent way to keep your Laravel application clean, readable, and maintainable. Whether you’re building a blog, an e-commerce site, or a SaaS product, query scopes help encapsulate common query logic and make your code more expressive.

Next time you find yourself repeating a query in multiple places, take a step back and consider creating a scope. Your future self (and your team) will thank you! 🙌

What’s Next?

• Explore more about Laravel Eloquent Scopes in the official documentation.
• Try combining multiple scopes in your next project.
• Share your experiences or scope-related tips in the comments below! 👇

Happy coding! 😄