In Laravel Eloquent, the global scope is automatically applied to each query, suitable for scenarios such as filtering inactive users; the local scope needs to be called manually, suitable for scenarios such as displaying published articles only in a specific context. 1. Global scope is implemented by implementing the Scope interface and registering in the model, such as adding the where('active', true) condition. 2. Local scope is a method in the model, starting with scope and can take parameters, such as scopeVerified() or scopeOfType(). 3. When using global scope, its impact on all queries should be considered, and if necessary, you can exclude it by withoutGlobalScopes(). 4. When selecting a scope, decide based on whether the conditions are always needed, and pay attention to the readability and testability of the code. 5. A simple global scope can be defined through closures to improve development efficiency.

In Laravel Eloquent, understanding how to define and use local and global scopes is key to writing clean, reusable, and maintainable code. Scopes help you filter query results without repeating the same conditions across your application. Here's how to make the most of them.

What's the difference between local and global scopes?

Global scopes apply automatically every time you query a model — like always filtering out deleted users or only fetching active records.
Local scopes , on the other hand, are applied manually when needed — for example, only showing published posts in certain contexts.

Knowing when to use each helps keep your logic organized and prevents bugs from unintended data exposure.

How to define a global scope

To create a global scope , you need to implement the Illuminate\Database\Eloquent\Scope interface. This involves defining a class with an apply method that adds constraints to the query.

For example, let's say you want to exclude inactive users globally:

 namespace App\Scopes;

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

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

Then, in your model:

 use App\Scopes\ActiveUserScope;

protected static function booted()
{
    static::addGlobalScope(new ActiveUserScope);
}

Now, every query on this model will include where active = true .

Note: You can bypass global scopes using methods like withoutGlobalScopes() or withoutGlobalScope(ActiveUserScope::class) if you ever need to fetch all records.

Creating and using local scopes

A local scope is simpler — it's just a method inside your model that starts with scope , followed by the name in camelCase.

For example, to define a scope that returns only verified users:

 public function scopeVerified(Builder $query): Builder
{
    return $query->whereNotNull('email_verified_at');
}

Then call it like this:

 User::verified()->get();

You can also add parameters:

 public function scopeOfType(Builder $query, string $type): Builder
{
    return $query->where('type', $type);
}

And use it like:

 User::ofType('admin')->get();

These scopes are great for reusing common filters without cluttering your controllers.

When to choose global vs local scopes

• Use global scopes when the condition should always be applied (like soft-deletes, tenant isolation, status checks).
• Use local scopes when the filter is context-dependent (eg, filtering by category, status, or custom user roles).

Also, consider readability and testability:

• Global scopes are powerful but can be harder to track down when debugging.
• Local scopes are more explicit and easier to understand at a glance.

Some tips:

• Document any global scopes so future developers know they exist.
• Don't overdo it with too many scopes — sometimes a simple where clause is clearer.
• Group related scopes into traits or base models if you find yourself copying them.

Bonus tip: Using anonymous global scopes

If your scope is simple, you can skip creating a separate class and use a closure directly in the model:

 use Illuminate\Database\Eloquent\Builder;
use Illuminate\Support\Facades\Auth;

protected static function booted()
{
    static::addGlobalScope('user_tenant', function (Builder $builder) {
        $builder->where('user_id', Auth::id());
    });
}

This is handy for quick filters that don't need reuse across multiple models.

Basically, scopes are one of those tools in Laravel that, once understand, make your code cleaner and more expressive. Whether you're applying a global rule or adding a conditional filter, knowing which scope to use and how keeps things running smoothly.

No magic — just smart, reusable query logic.

The above is the detailed content of Defining and using local and global scopes in Laravel Eloquent. For more information, please follow other related articles on the PHP Chinese website!