跳转到主内容
趣航编程网 - 趣学编程,启航技术之路!

Laravel如何使用Scope本地作用域_Laravel模型常用查询逻辑封装技巧【手册】

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

相关文章