Laravel Custom Query Builders Over Scopes

Hello 👋

Alright, let's talk about Query Scopes. They're awesome, they make queries much easier to read, no doubt about it. But there's one thing I hate about them: magic. And when you're working with a team where not everyone is a backend developer, it can make their lives miserable. Sure, you can add PHPDocs, but there’s always some magic going on. If you've never used scopes before, no worries, hang tight bud.

So, What Are Scopes? 🤔

Consider this code:

use App\Models\User;

$users = User::query()
    ->where('votes', '>', 100);
    ->where('active', 1);
    ->orderBy('created_at')
    ->get();

This is how you would typically write queries. But when queries become too complex or hard to read, you can abstract them into scopes:

<?php

namespace App\Models;

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

class User extends Model
{
    public function scopePopular(Builder $query): void
    {
        $query->where('votes', '>', 100);
    }

    public function scopeActive(Builder $query): void
    {
        $query->where('active', 1);
    }
}

Now you can do this:

$users = User::query()
    ->popular()
    ->active()
    ->orderBy('created_at')
    ->get();

Reads much better right? I know. But the issue is, you don't get any autocompletion. This is dark magic to the IDE. Since scopes are resolved at runtime and prefixed with scope, there is no way your IDE knows about them unless you help it out.

One way is through PHPDocs, like so:

/**
 * @method static Builder popular()
 * @method static Builder active()
 */
class User extends Model

Another downside to scopes? The most frequently used models end up bloated with tons of them, for nothing. I love skimming through my models and immediately seeing the relationships and core logic, not a bunch of query abstractions.

Sooo? Do we just ditch scopes and move on? Well, that's an option, or you could use custom query builders.

Custom Query Builders 😎

As the name suggests, a custom query builder let's you move all your query abstractions into a dedicated class. The code will be more organized in a way.

Let's create a new class UserQueryBuilder:

<?php

namespace App\Eloquent\QueryBuilders;

use App\Models\User;
use Illuminate\Database\Eloquent\Builder;

class UserQueryBuilder extends Builder
{
    public function popular(): self
    {
        return $this->where('votes', '>', 100);
    }

    public function active(): self
    {
        return $this->where('active', 1);
    }
}

Where to put builders? There is no guideline, but I personally like to place them in app/Eloquent/QueryBuilders.

Now let's use this builder in the User model:

<?php

namespace App\Models;

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

class User extends Model
{
    public function newEloquentBuilder($query): UserQueryBuilder
    {
        return new UserQueryBuilder($query);
    }

    // for type hints
    public static function query(): UserQueryBuilder
    {
        return parent::query();
    }
}

And just like that, you can now do:

$users = User::query()
    ->popular()
    ->active()
    ->orderBy('created_at')
    ->get();

Works exactly the same, and you get full autocompletion. Plus, code navigation works perfectly, it takes you where you need to be 🙌

Another cool thing is you can dynamically resolve query builders if needed.

public function newEloquentBuilder($query): UserQueryBuilder
{
    if ($this->status === State::Pending) {
        return new PendingUserQueryBuilder($query); // extends UserQueryBuilder
    }

    return new UserQueryBuilder($query);
}

This way you avoid having one big query builder when you can group queries by context (like a state).

That's it ✅

Scopes are cool, and if I only have 2-3 of them, I'll stick with them. But when things start to get out of hand, custom query builders are the way to go. They are worth the extra effort, keeping your code clean, organized, and easier to maintain 🚀