Laravel 模型全局作用域：自动为所有查询添加 where 条件-php教程-PHP中文网

Laravel 模型全局作用域：自动为所有查询添加 where 条件

通过 Laravel 的全局作用域（Global Scopes），可让模型在每次查询时自动附加指定条件（如 where('status', 1)），无需重复书写，实现类似软删除的透明过滤机制。

通过 laravel 的全局作用域（global scopes），可让模型在每次查询时自动附加指定条件（如 `where('status', 1)`），无需重复书写，实现类似软删除的透明过滤机制。

在 Laravel 中，若需对某个模型的所有 Eloquent 查询统一添加默认约束（例如只允许查询 status = 1 的活跃记录），推荐使用 全局作用域（Global Scopes） —— 这是 Laravel 官方提供的、专为解决此类问题而设计的机制，比局部作用域（Local Scopes）或重写 newQuery() 更安全、更规范。

✅ 正确实现方式：定义全局作用域

首先，创建一个作用域类（推荐放在 app/Scopes 目录下）：

// app/Scopes/ActiveScope.php
<?php namespace App\Scopes;

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

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

然后，在目标模型中注册该全局作用域：

// app/Models/Model.php
<?php namespace App\Models;

use App\Scopes\ActiveScope;
use Illuminate\Database\Eloquent\Model;

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

✅ 此后所有查询将自动生效：

Laravel 13.2.0

PHP中文网提供Laravel 13.2.0版本下载，Laravel框架是基于 PHP 8.3+ 的高性能框架，官方推荐通过 Composer 安装。它内置 AI SDK、JSON:API Resources 及原生向量搜索，支持属性驱动开发与队列路由，大幅提升开发效率。相比旧版，13.2.0 优化了缓存 TTL 管理与实时通信，无需 Redis 即可横向扩展。作为现代 Web 开发首选，它兼顾安全与极速体验，助您快速构建企业级应用。

下载

Model::first();                    // 等价于 SELECT * FROM models WHERE status = 1 LIMIT 1
Model::where('name', 'test')->get(); // 等价于 SELECT * FROM models WHERE status = 1 AND name = 'test'
Model::withTrashed()->get();       // ❌ 仍受限制 —— 注意：全局作用域默认无法绕过

⚠️ 重要注意事项

不可绕过性：全局作用域默认强制应用；如需临时取消（例如后台管理需查看全部状态），可使用 withoutGlobalScopes() 或 withoutGlobalScope(ActiveScope::class)：
```
Model::withoutGlobalScopes()->get(); // 完全忽略所有全局作用域
Model::withoutGlobalScope(ActiveScope::class)->get(); // 仅忽略 ActiveScope
```
避免与 SoftDeletes 冲突：若同时使用 SoftDeletes，两个全局作用域会共存（Laravel 默认已为 SoftDeletes 注册 SoftDeletingScope），彼此独立，互不影响。
慎用 newQuery() 替代方案：虽然重写模型的 newQuery() 方法也能达到类似效果，但会破坏 Eloquent 内部作用域链逻辑，且难以调试和维护，不推荐。