ThinkPHP模型字段过滤详解

本文深入解析了ThinkPHP中模型字段过滤的核心机制，明确指出只有`$allowField`这一白名单属性能在数据写入前可靠拦截非法字段，而`$field`、`$visible`、`field()`等仅作用于查询或输出，完全不参与输入防护；文章不仅剖析了`$allowField`为何是唯一可靠方式，还详解了其正确声明规范、动态控制的安全方案（如`allowField()`链式调用和控制器层`only()`预过滤），并重点揭示了易被忽视的绕过场景——如直连Db类、`save($data, true)`强制写入、钩子后门赋值及关联模型独立过滤需求，强调真正的安全必须从前端请求入口统一收口，而非仅依赖模型配置。

只接收指定字段数据，必须用 $allowField，不是 $field、$visible 或 field() 方法——后三者只管输出或查询，不拦输入。

为什么 $allowField 是唯一可靠方式

ThinkPHP 模型的 create()、save()、update() 等写入操作，默认会把传入的所有键值都尝试写进数据库。不设防，就等于开放任意字段注入。

• $allowField 是模型层的白名单过滤，在数据进入 data() 之前就筛掉非法字段
• field() 是查询构造器方法，只影响 SELECT 字段，对 save() 无效
• $visible 和 $hidden 只控制 toArray()/JSON 输出，完全不干预写入流程
• 靠控制器里手动 only(['id', 'name']) 或 except(['token']) 容易漏——比如关联模型、批量更新、事件回调里绕过

$allowField 的正确声明与常见错误

它必须是 protected 属性，且值为数组；public 或 private 声明直接失效。

• 正确写法：protected $allowField = ['id', 'title', 'status'];
• 错误写法：public $allowField = [...]; 或 private $allowField = [...]; —— 模型完全忽略
• 字段名必须和数据库列名严格一致（含大小写），比如数据库是 user_name，就不能写成 userName
• 如果用了访问器（如 setPasswordAttr），$allowField 仍按原始属性名判断，不是数据库字段名

动态控制允许字段的两种安全做法

硬编码 $allowField 在多接口场景下太死板，但动态设置不能靠临时赋值——模型类属性是静态的，运行时改不生效。

• 方案一：用 allowField() 方法链式调用（TP6.0+）
  UserModel::create($data)->allowField(['id', 'email']);
  注意：必须在 create/save 前调用，且只对当前实例有效
• 方案二：在控制器中先用 only() 过滤再传给模型
  $data = $request->only(['id', 'title', 'status']);
UserModel::create($data);
  比模型层过滤多一层，但更可控，尤其适合参数来源复杂（如 form 表单 + JSON body 混合）

容易被忽略的绕过点

$allowField 能拦住绝大多数写入，但以下情况它不生效：

• 使用 Db::table('user')->insert($data) 绕过模型——此时没有任何字段过滤，全靠手写 only()
• 调用 save($data, true) 的 force 参数强制写入——true 会跳过 $allowField 和自动完成
• 在 beforeWrite 钩子里手动 $model['xxx'] = $value —— 这个赋值发生在过滤之后，相当于“后门写入”
• 关联模型的写入不受主模型 $allowField 约束，每个关联模型需各自定义

真正要堵死入口，得在请求层统一收口，而不是只依赖模型配置。

理论要掌握，实操不能落！以上关于《ThinkPHP模型字段过滤详解》的详细介绍，大家都掌握了吧！如果想要继续提升自己的能力，那么就来关注golang学习网公众号吧！