laravel 局部作用域通过以 scope 开头的模型方法封装重复查询条件，支持无参（如 active()）、带参（如 oftype('admin')）、链式组合、when 动态启用及 callscope 手动调用五种用法。
如果您在 Laravel 项目中频繁使用相同查询条件（如 status = 'active' 或 type = 'admin'），但每次都在控制器或服务中重复书写 where 语句，则可借助局部作用域将这些逻辑封装进模型内部。以下是具体使用方法：
一、定义基础局部作用域
局部作用域是定义在 Eloquent 模型类中的公共方法，以 scope 开头，Eloquent 会在链式调用时自动注入查询构造器实例，并支持链式延续。
1、在模型类（如 User.php）中声明一个以 scope 开头的公共方法，例如 scopeActive；
2、该方法必须接收第一个参数 $query（类型为 Illuminate\Database\Eloquent\Builder）；
3、在方法体内调用 $query->where() 添加条件，并确保 return $query；
4、保存后即可在查询中以 active() 形式调用，无需 scope 前缀。
二、定义带参数的局部作用域
当查询条件需动态传入（如按年份、ID 或关键词过滤），局部作用域可接受额外参数，实现灵活复用，且参数顺序必须紧随 $query 之后。
1、在模型中定义方法名如 scopeOfType，签名形如 scopeOfType($query, $type)；
2、在方法内使用 $query->where('type', $type) 绑定参数值；
3、调用时直接传参：User::ofType('admin')->get()；
4、支持多个参数，例如 scopePublishedAfter($query, $from, $to)，对应调用为 ->publishedAfter('2024-01-01', '2026-01-01')。
三、组合多个局部作用域进行链式调用
局部作用域设计天然支持链式语法，多个作用域可连续调用，Eloquent 会依次将每个作用域的查询条件合并进最终 SQL，提升语义清晰度与可读性。
1、确保每个作用域方法均返回 $query，否则链式中断；
2、在控制器中按业务意图顺序调用，例如 Post::published()->popular()->orderBy('views', 'desc')；
3、链式调用不改变原始模型实例，所有条件均作用于当前查询构造器；
4、可混合使用 Eloquent 原生方法（如 where()、with()）与自定义作用域。
四、使用 when 方法动态启用局部作用域
当某些查询条件仅在特定条件下才需应用（如搜索关键词存在时才执行模糊匹配），可结合 when() 高阶函数实现惰性调用，避免冗余条件污染查询。
1、在查询链中调用 when($condition, function ($query) { ... })；
2、在闭包内显式调用局部作用域，例如 $query->active()；
3、若 $condition 为 false，整个闭包被跳过，作用域不生效；
4、也可直接传入作用域方法名字符串，如 when($search, 'searchByName')，前提是该作用域已定义且接收单个参数。
五、通过 callScope 手动触发局部作用域
在极少数场景下（如作用域名由变量决定、或需在非链式上下文中复用逻辑），可绕过常规调用方式，使用模型实例的 callScope() 方法显式执行。
1、获取模型查询构造器实例：$builder = User::query();；
2、调用 $builder->callScope('active');，等效于 $builder->active();；
3、若作用域带参数，需以数组形式传入后续参数：$builder->callScope('ofType', ['admin']);；
4、该方式适用于构建通用查询服务类或封装动态筛选器逻辑。
