Comparison between Scopes + Traits × UseEloquentBuilder in Laravel

Laravel provides multiple ways to write reusable query logic. The two most common approaches are using Scopes with Traits or the newer #[UseEloquentBuilder] feature introduced in Laravel 12.19.

🔹 First: Using Scopes with Traits

Scopes are simple methods that begin with scope and live in your Eloquent models. You can group them into Traits to reuse across multiple models.

Example Trait with multiple scopes:

// app/Traits/ArticleScopes.php
namespace App\Traits;

trait ArticleScopes {
    public function scopePublished($query) {
        return $query->where('is_published', true);
    }

    public function scopeRecent($query, $days = 7) {
        return $query->whereDate('created_at', '>=', now()->subDays($days));
    }

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

Usage in your model:

// app/Models/Article.php
use App\Traits\ArticleScopes;

class Article extends Model {
    use ArticleScopes;
}

And using it in a query:

$articles = Article::published()->recent(30)->byAuthor(5)->paginate(10);

✅ Advantages:

• Quick and easy to implement.
• Reusable across different models.
• Minimal boilerplate.

❌ Disadvantages:

• Query logic can be spread across many traits.
• Limited IDE support for autocomplete or type inference.
• Harder to test scopes in isolation.

🔹 Second: #[UseEloquentBuilder] in Laravel 12.19

With Laravel 12.19, you can now declare a dedicated Builder class for each model using the #[UseEloquentBuilder] attribute, making your query logic more organized and type-safe.

Custom Builder Example:

// app/Builders/ArticleBuilder.php
namespace App\Builders;

use Illuminate\Database\Eloquent\Builder;

class ArticleBuilder extends Builder {
    public function published(): static {
        return $this->where('is_published', true);
    }

    public function recent(int $days = 7): static {
        return $this->whereDate('created_at', '>=', now()->subDays($days));
    }

    public function byAuthor(int $authorId): static {
        return $this->where('author_id', $authorId);
    }
}

Apply it to your model:

// app/Models/Article.php
namespace App\Models;

use App\Builders\ArticleBuilder;
use Illuminate\Database\Eloquent\Attributes\UseEloquentBuilder;

#[UseEloquentBuilder(ArticleBuilder::class)]
class Article extends Model {
    // No need to override newEloquentBuilder
}

Query using the custom builder:

$articles = Article::query()->published()->recent(15)->byAuthor(2)->get();

✅ Advantages:

• Centralized query logic – easy to manage.
• Excellent IDE support (autocomplete and type hints).
• Testable as standalone logic.
• More flexible method naming than scopes.

❌ Disadvantages:

• Requires more boilerplate (builder class per model).
• May feel overkill for very simple applications.

📊 Quick Comparison:

🧠 Conclusion:

If your app is small and only needs a few reusable queries, Scopes + Traits are sufficient. But for more advanced or scalable projects, #[UseEloquentBuilder] offers a much cleaner and maintainable approach to query management.