如何定义ThinkPHP的查询范围_scope局部作用域复用SQL条件代码块-ThinkPHP-PHP中文网

_scope是thinkphp 5.0前用于预设查询条件的静态数组，因不支持动态参数、无法链式调用且复用性差，tp5.1+已彻底移除；现统一使用public static作用域方法或闭包实现灵活查询。

如何定义thinkphp的查询范围_scope局部作用域复用sql条件代码块

ThinkPHP 的 `_scope` 是什么，为什么现在基本不用了

ThinkPHP 5.0 之前版本支持的 _scope 属性，本质是类里定义的一个数组，用来预设命名查询条件，比如 'hot' => ['status' => 1, 'views' => ['gt', 1000]]。但它只在模型实例化时静态合并进查询，不支持动态参数、不走闭包、不能链式调用，实际复用性极低。TP5.1+ 已彻底移除该机制，文档里也找不到它——如果你在旧项目里看到它，说明你正在维护一个已停止维护的 TP 版本。

替代方案：用 `scope` 静态方法 + 闭包更灵活

TP5.1 起统一改用静态方法定义作用域，核心是让方法接收 $query 对象并直接操作它。这种方式能读取参数、组合条件、甚至嵌套调用其他 scope，真正实现“SQL 条件代码块”的复用。

常见错误现象：scope 方法没加 static 关键字，或返回了数组而不是 void；调用时漏写 -> 或拼错方法名导致静默失效。

必须声明为 public static，且第一个参数是 $query
方法体内直接调用 $query->where(...)，不要 return 任何东西
调用时用 ->scope('hot') 或 ->scope(['hot', 'top'])，不是 ::scope()
支持传参：定义 public static function scopeHot($query, $min = 1000)，调用时写 ->scope('hot', 5000)

class Article extends Model
{
    public static function scopeHot($query, $min = 1000)
    {
        $query->where('status', 1)->where('views', '>=', $min);
    }
    
    public static function scopeTop($query)
    {
        $query->order('created_time', 'desc')->limit(10);
    }
}

// 使用
Article::scope('hot', 2000)->scope('top')->select();

更现代的做法：用查询作用域配合 `use` 闭包封装通用逻辑

当条件逻辑变复杂（比如要查“本周热门”，需动态算时间范围），静态方法就显得笨重。这时直接在查询链里用闭包更直观，还能捕获外部变量，避免 scope 方法膨胀。

容易踩的坑：use ($var) 漏写括号、闭包里误用 $this（此时没有实例上下文）、闭包未被调用（忘了加 ->where(function ($q) { ... })）。

闭包必须作为 where 的第二个参数传入，第一个是空字符串或字段名
需要访问模型属性时，改用 self::where(...) 或提前把值 extract 出来
多个相似闭包建议抽成独立函数，放在 app/common/QueryScopes.php 里 require_once

$weekStart = date('Y-m-d', strtotime('-6 days'));
$weekEnd   = date('Y-m-d');

Article::where('status', 1)
       ->where(function ($query) use ($weekStart, $weekEnd) {
           $query->whereBetween('created_time', [$weekStart, $weekEnd]);
       })
       ->where('views', '>=', 100)
       ->select();

scope 和闭包混用时的执行顺序和覆盖风险

scope 方法里的 where 和链式调用的 where 共享同一个查询对象，后写的会覆盖同字段的前写条件——这不是 bug，是 QueryBuilder 的设计逻辑。比如 scopeHot() 设了 status=1，后面又写 ->where('status', 0)，最终就是 status=0。