PHP怎么处理Eloquent Scopes查询作用域复用_Laravel查询逻辑封装【指南】-php教程-PHP中文网

本地作用域必须返回 $query 实例才能维持链式调用，方法需以 scope 开头、声明为 public，且不可访问 $this 实例属性；带参作用域须严格类型声明并处理空值，避免传入请求上下文对象。

php怎么处理eloquent scopes查询作用域复用_laravel查询逻辑封装【指南】

本地作用域必须返回 $query，否则后续的 where、orderBy 会直接报错或静默失效。Eloquent 在调用时自动把当前 Builder 实例传入第一个参数，你不能把它当普通实例方法来用。

错误写法：public function scopeActive($query) { $query->where('status', 'active'); } —— 少了 return
正确写法：public function scopeActive($query) { return $query->where('status', 'active'); }
别在作用域里访问 $this->id 或其他模型实例属性 —— 此时模型还没从数据库加载出来
方法必须是 public，且命名严格以 scope 开头（如 scopeLatest），调用时写 ->latest()

参数类型不匹配、空值未处理、或传了不该传的对象，是本地作用域最常翻车的地方。PHP 8+ 的严格类型检查会让这类问题立刻暴露，但低版本可能只在运行时崩掉。

明确声明类型：public function scopeWithinDays($query, int $days = 7)，避免传字符串 '30' 导致 subDays() 报错
对可为空参数做兜底：public function scopeByCategory($query, ?string $category = null) { return $category ? $query->where('category', $category) : $query; }
别传 Request 或 Auth 实例进作用域 —— 本地作用域不是控制器，不该耦合请求上下文
测试时用 User::where('name', 'test')->byCategory('admin')->get() 直接验证，比写单元测试更快定位参数问题

全局作用域在 CLI 或队列任务中拿不到 HTTP 请求上下文，硬编码从 session() 或 request() 取租户 ID，必然导致条件为空或报错。

Laravel Cloud

Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。

下载

租户 ID 必须通过服务容器解析（如 app(TenantManager::class)->currentId()），这个类需支持 CLI 环境下的 fallback 逻辑
不要在 apply() 里写 whereNotNull('tenant_id') 这类兜底 —— 它会污染真实查询，让 forceDelete() 也带上条件
remove() 方法不是摆设：数据迁移时用 Model::withoutGlobalScopes()->get()，但得确保它真能跳过你的全局作用域（有些实现漏写了 remove()）
全局作用域不适用于软删除：Laravel 自带的 SoftDeletes trait 已内置控制逻辑，再加一层全局 whereNull('deleted_at') 会导致 restore() 失效

直接在作用域里写 whereNull('deleted_at') 很危险 —— 如果模型没用 SoftDeletes trait，这个条件就变成无意义的过滤，还可能掩盖业务逻辑错误。

必须加保护判断：if (static::usesSoftDelete()) { $query->whereNull('deleted_at'); }
别在 boot() 里用 addGlobalScope() 强制加软删除条件 —— 官方明确反对，restore() 和后台列表都会出问题
日常就用 Model::withoutTrashed()，它已内置安全判断；只有需要封装语义（比如叫 scopePublished()）才自己写作用域
如果同时用了 scopeWithoutTrashed() 和 withoutTrashed()，SQL 里会出现两个 WHERE deleted_at IS NULL，查不到数据却很难排查