Defining a Dedicated Query Builder in Laravel 12 With PHP Attributes

The Laravel 12.19 release introduced the UseEloquentBuilder PHP attribute to define a custom query builder for your model. Models don't typically need a custom query builder, but you can use this technique to thin out models, group scopes in one central place, and include custom query builder methods you'll reuse in your application.

Before Laravel 12.19, you would override a model's query builder by overriding the newEloquentBuilder() method and returning an instance of your custom query builder.

public function newEloquentBuilder($query)
{
    return new CustomBuilder($query);
}

When defining a custom query builder, your Builder class must implement the Builder contract. The easiest way to do that is by exending Laravel's Builder class:

namespace App\Builder;
 
use Illuminate\Database\Eloquent\Builder;
 
class PostBuilder extends Builder
{
    public function wherePublished()
    {
        $this->whereNotNull('published_at');
 
        return $this;
    }
 
    /* ... */
}

Here's how you can configure your custom builder instance using the UseEloquentBuilder attribute instead of overriding the newEloquentBuilder() method on the base model:

namespace App\Models;
 
use App\Builder\PostBuilder;
use Illuminate\Database\Eloquent\Attributes\UseEloquentBuilder;
use Illuminate\Database\Eloquent\Model;
 
#[UseEloquentBuilder(PostBuilder::class)]
class Post extends Model
{
    /* ... */
}
 
// Usage
Post::query()->wherePublished()->get();

As with various things in Laravel, I suggest going with the convention first (use the built-in query builder instance) and moving to a dedicated query builder instance when it makes sense for your needs. You can be the judge of whether and when you introduce a dedicated query builder instance on a model.

#Learn More

To learn more about UseEloquentBuilder, check out the release notes in Laravel 12.19 and Pull Request #56025 for implementation details. You can also learn more about Laravel's database query builder documentation.