How to Use Global Scope in Eloquent: Laravel Guide

In Laravel Eloquent, you use a Global Scope by creating a class that implements the Scope interface and applying it in your model's booted method. This automatically adds query constraints to all queries for that model without repeating conditions.

Syntax

To use a global scope, create a class implementing Scope with an apply method, then add it in your model's booted method using static::addGlobalScope().

• Scope: Interface to define the scope logic.
• apply(): Method to add constraints to the query.
• booted(): Model method to register the global scope.

php

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

class ActiveScope implements Scope
{
    public function apply(Builder $builder, Model $model)
    {
        $builder->where('active', 1);
    }
}

class User extends Model
{
    protected static function booted()
    {
        static::addGlobalScope(new ActiveScope());
    }
}

Example

This example shows a User model with a global scope that only fetches users where active is 1. All queries on User will automatically include this condition.

php

<?php

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

class ActiveScope implements Scope
{
    public function apply(Builder $builder, Model $model)
    {
        $builder->where('active', 1);
    }
}

class User extends Model
{
    protected static function booted()
    {
        static::addGlobalScope(new ActiveScope());
    }
}

// Usage
$users = User::all(); // Only users with active = 1 are returned

// To ignore the global scope:
$allUsers = User::withoutGlobalScope(ActiveScope::class)->get();

Output

Collection of User models where 'active' = 1

Common Pitfalls

Common mistakes include:

• Not adding the global scope in the booted method, so it never applies.
• Forgetting to import the Scope interface or using incorrect namespaces.
• Trying to use global scopes for complex logic better suited for local scopes.
• Not knowing how to remove or ignore global scopes when needed.

Always test queries to ensure the scope applies as expected.

php

/* Wrong: Adding scope in constructor (won't work) */
class User extends Model
{
    public function __construct()
    {
        static::addGlobalScope(new ActiveScope()); // This is incorrect
    }
}

/* Right: Use booted method */
class User extends Model
{
    protected static function booted()
    {
        static::addGlobalScope(new ActiveScope());
    }
}

Quick Reference

• Create a Scope: Implement Scope interface with apply().
• Apply Scope: Use static::addGlobalScope() inside booted() method of model.
• Ignore Scope: Use withoutGlobalScope() to remove it from queries.
• Use Cases: Ideal for filtering active records, soft deletes, or tenant-specific data.

Key Takeaways

Global scopes automatically add query constraints to all model queries.

Define global scopes by implementing the Scope interface and applying them in the booted method.

Use withoutGlobalScope() to exclude a global scope from specific queries.

Avoid adding global scopes outside the booted method to ensure they work correctly.

Global scopes are perfect for common filters like active status or multi-tenant data.