本地作用域是Laravel模型中以scope开头的静态方法,用于封装常用查询条件,必须显式调用;定义时需为public static,首参为$query,支持驼峰转短横线调用;调用不可省略括号,且scope内应避免直接使用orWhere以防逻辑错误。
什么是本地
作用域
(Local Scope)
本地作用域是 Laravel 模型中以
开头的静态方法,用于封装常用查询条件。它不是全局生效的,必须显式调用,比如
中的
和
就是两个本地作用域。
如何定义和调用 scope 方法
scope 方法必须是
、
,且第一个参数固定为
(即
实例),后续参数按需添加。Laravel 会自动把驼峰命名转为短横线调用(如
可链式调用为
)。
调用方式:
注意:不能省略括号,哪怕无参也要写
,写成
会报错
。
scope 和 where 系列方法混用时的执行顺序
本地作用域本质是提前拼接
条件,所有 scope 调用顺序与
链式调用顺序一致,最终生成 SQL 的
子句是「从左到右」叠加的。但 scope 内部若用了
,容易引发意料外的逻辑分组问题。
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 开发首选,它兼顾安全与极速体验,助您快速构建企业级应用。
下载
安全写法:scope 内统一用
、
等 AND 类型约束
风险写法:在 scope 里直接写
,会导致该条件脱离主 AND 分组,可能查出不该出现的数据
若真需要 OR 逻辑,应改用
显式包裹,例如:
scope 无法复用到关联查询?试试 has() 或 withWhereHas()
本地作用域只作用于当前模型的主查询,不会自动下推到
加载的关联模型中。比如
中的
只过滤 User,不筛选 Posts。
要限制关联数据,得用:
—— 推荐,清晰可控
—— 用于「用户有活跃文章」这类存在性筛选
(Laravel 10.29+)—— 同时满足「加载 + 筛选」,且主模型也参与关联条件过滤
别指望给
定义的
能在
里自动生效;scope 不是魔法,它只是语法糖,背后仍是手动拼 query。
scopeUser::popular()->active()->get()popular()active()publicstatic$queryBuilderscopeLatestPublished()->latestPublished()class Post extends Model
{
public function scopeActive($query)
{
return $query->where('status', 'active');
}
public function scopeByCategory($query, $category)
{
return $query->where('category', $category);
}
public function scopePopular($query, $minViews = 100)
{
return $query->where('views', '>=', $minViews);
}
}Post::active()->get()Post::byCategory('news')->get()Post::popular(50)->get()->active()->activeCall to undefined method Illuminate\Database\Query\Builder::active()wherewhereWHEREorWherewherewhereIn$query->orWhere(...)where(function ($q) { ... })$query->where(function ($q) {
$q->where('status', 'draft')->orWhere('status', 'pending');
});with()User::with('posts')->active()->get()active()with(['posts' => function ($q) { $q->active(); }])whereHas('posts', function ($q) { $q->active(); })withWhereHas('posts', function ($q) { $q->active(); })PostscopeActive()User::with('posts')