作用域方法须以scope开头、public且返回$query;全局作用域需实现Scope接口并在booted()注册;访问器/修改器基于属性名驼峰转换,仅作用于PHP层,不影响SQL查询。

scope 方法名必须以 scope 开头,调用时去掉前缀转驼峰
本地作用域本质是模型里的普通 public 方法,但 Laravel 会识别 scope 前缀并自动挂载为查询链可调用的方法。方法第一个参数固定是 $query(Illuminate\Database\Eloquent\Builder 实例),返回值必须是该 $query 对象本身(支持链式)。
常见错误:漏掉 return $query,导致后续调用报错“Call to a member function get() on null”;或者把方法写成 private 或 protected,Laravel 就找不到它。
- 定义正确写法:
public function scopeActive($query) { return $query->where('status', 'active'); } - 调用方式:
User::active()->get(),不是User::scopeActive()->get() - 带参数的作用域:
public function scopeWhereTitle($query, $title) { return $query->where('title', 'like', "%{$title}%"); },调用:Post::whereTitle('Eloquent')->get() - 多个作用域可链式组合:
Post::published()->whereTitle('Scope')->orderBy('created_at')->get()
全局作用域需实现 Scope 接口,并在 booted() 中注册
全局作用域不是模型方法,而是一个独立类,必须实现 Illuminate\Database\Eloquent\Scope 接口,且只实现 apply() 方法。它会在所有该模型的查询中自动生效——包括 find()、first()、count(),甚至关联预加载里的子查询。
容易踩的坑:直接在 boot() 里注册,但 boot() 可能被多次调用;应改用 booted()(静态方法,只执行一次)。另外,忘记移除全局作用域会导致调试困难,比如软删除后查不到数据却没报错。
- 注册方式:
protected static function booted() { static::addGlobalScope(new ActiveScope); } - 临时跳过:
User::withoutGlobalScopes()->get()或指定某一个:User::withoutGlobalScope(ActiveScope::class)->get() - 软删除(
SoftDeletes)就是靠全局作用域实现的,它自动加where null on deleted_at条件
访问器 get{Attribute}Attribute 和修改器 set{Attribute}Attribute 匹配字段名有转换规则
访问器和修改器的命名不是直接对应数据库字段,而是基于「属性名」——即模型里通过 $fillable 或动态访问的键名。Laravel 把蛇形字段(如 user_name)自动转为驼峰(userName),再拼上前缀构成方法名。
这个转换容易误判:比如字段叫 is_admin,对应修改器是 setIsAdminAttribute(),不是 setIsadminAttribute();若字段含多个下划线(first_name_last_name),会变成 firstNameLastName,但这种命名本身就不推荐。
- 修改器只在模型赋值时触发:
$user->user_name = 'ABC'或User::create(['user_name' => 'ABC']),对DB::table()->update()完全无效 - 访问器只在读取时触发:
echo $user->user_name,但$user->attributes['user_name']绕过访问器,直接拿原始值 - 时间字段别硬写修改器:
setCreatedAtAttribute()是危险操作,应改用$casts = ['created_at' => 'datetime']
作用域和访问器/修改器互不干扰,但组合使用时要注意执行时机
作用域影响 SQL 查询条件,发生在数据库层面;访问器/修改器只处理 PHP 层的数据进出,不参与生成 WHERE 或 SELECT 字段。这意味着:你在作用域里用 where('user_name', 'john'),匹配的是数据库原值;而 $user->user_name 输出的却是访问器加工后的结果——两者根本不在同一层。
一个典型陷阱:定义了 setUserNameAttribute() 把输入转小写存库,又定义了 getUserNameAttribute() 把输出首字母大写。这时你用 User::where('user_name', 'John')->first() 查不到记录,因为库里存的是 john,但你却按 John 去查。
- 搜索场景下,如果业务要求“忽略大小写查用户名”,应在作用域里统一处理:
$query->whereRaw('lower(user_name) = ?', [strtolower($name)]) - 不要指望修改器能改变查询行为——它只改写入值,不改查询条件
- 全局作用域 + 修改器组合时,尤其注意软删除字段(
deleted_at)是否也被其他修改器意外覆盖


















