Scope 不是配置项，也不是静态属性，而是模型里以 scope 开头的 public 方法；它不返回数据，只拼条件，且必须操作传入的 $query 对象。
scope 方法必须声明为 public 且接收 $query 参数
ThinkPHP 的 scope 本质是链式查询的“条件注入点”，不是普通工具函数。方法签名错一个字（比如写成 protected、漏掉 $query 参数、或加了 return []），就会导致静默失效或链路中断。
正确写法：public function scopeHot($query) { $query->where(‘status’, 1)->where(‘views’, ‘>=’, 1000); }错误写法：protected function scopeHot() { return [‘status’ => 1]; } —— 权限不对 + 没参数 + 返回数组错误写法：public function scopeHot($query) { return $query->where(…)->select(); } —— 不能执行 select()，只负责拼条件调用时必须走模型实例或门面：User::scope(‘hot’)->select()，不能写 User::scopeHot() 或 User::scope(‘hot’, 1000)（除非方法定义了第二个参数）
带参 scope 的传参方式和常见错因
scope 支持传参，但 ThinkPHP 对参数传递有明确规则：单个值直接跟在 scope 名后，多个参数需封装进关联数组，且方法签名必须匹配。
User::scope(‘hot’, 5000)->select() → 要求方法定义为 scopeHot($query, $min = 1000)User::scope([‘hot’ => 5000, ‘top’ => 10])->select() → 要求方法定义为 scopeHot($query, $params = [])，再从 $params[‘hot’] 取值如果方法没声明第二个参数，却传了值，PHP 会发 Warning，但 $min 始终为 null，条件可能不生效避免在 scope 内做类型强转，比如把字符串 ‘7’ 直接喂给 subDays()，建议加 is_numeric() 或类型声明 int $days
scope 组合调用与顺序敏感性
多个 scope 同时使用时，SQL 条件按调用顺序拼接，AND 关系下顺序一般不影响结果，但涉及 order、limit、group 等子句时，顺序决定最终行为。
立即学习“PHP免费学习笔记（深入）”；
User::scope(‘latest’)->scope(‘active’)->select()：先排好序再过滤状态，ORDER BY 在 WHERE 前，没问题User::scope(‘active’)->scope(‘latest’)->select()：先过滤再排序，更符合直觉，也更安全User::scope(‘hot’)->scope(‘top’)->select() 中，若 scopeTop() 包含 limit(10)，而 scopeHot() 返回 500 条，最终只取前 10 条 —— 这是预期行为，但容易被忽略调试时用 User::scope(‘hot’)->buildSql() 看生成的 SQL，确认条件是否如你所想
scope 和全局作用域（globalScope）共存时的冲突风险
全局作用域（如软删除的 delete_time IS NULL）每次查询自动附加，scope 是显式调用。两者叠加时，全局条件永远在外层包裹 scope 条件，一旦逻辑冲突，查不到数据也不报错。
例如：全局 scope 加了 status = 1，你在 scopeHot() 里又写 $query->where(‘status’, 2)，最终 SQL 是 WHERE status = 1 AND status = 2用 User::withoutGlobalScope()->scope(‘hot’)->select() 临时关闭全局作用域，验证是否是冲突导致空结果不要在 scope 里重复写全局作用域已覆盖的字段，比如全局已限定 tenant_id = ?，就别在 scope 里再 where(‘tenant_id’, …)关联查询（with()）不会继承 scope 条件，这是 ThinkPHP 的设计限制，需单独对关联模型调用 scope
真正难的不是写几个 scope 方法，而是搞清 $query 是谁传的、在哪被改、什么时候被最终执行 —— 它不保存状态，只是一次性的 Builder 实例。写完 scope 后，务必用 buildSql() 看 SQL，而不是靠“应该没错”去上线。
评论(0)