onBeforeInsert 是 ThinkPHP 模型新增前触发的静态事件钩子，需严格命名、声明为 static，并在 init() 中注册；接收 $data 数组用于预处理，返回 false 可中断插入。
ThinkPHP 中的 onBeforeInsert 是模型新增数据前自动触发的事件钩子，用于在数据写入数据库之前执行预处理逻辑，比如字段赋值、数据校验、加密或关联操作。它不是定义即生效，需满足几个关键条件才能正常运行。
onBeforeInsert 必须是静态方法且命名严格
该方法必须声明为 static，且函数名必须完全为 onBeforeInsert（注意大小写和下划线）。不能写成 beforeInsert、_before_insert 或其他变体——这些属于旧版本（如 ThinkPHP 3.2）的写法，在 5.x/6.x 中已失效。
- 正确写法：
protected static function onBeforeInsert($data) - 错误写法：
protected function _before_insert()（TP3 风格，不兼容） - 错误写法：
public function onBeforeInsert()（非 static，不会被框架调用）
事件必须显式注册才生效
即使方法写对了，若未注册，框架根本不会调用它。推荐在模型的 init() 方法中统一注册：
- 在模型类中添加
protected static function init() - 内部调用
self::event('before_insert', [static::class, 'onBeforeInsert']) - 注册后，所有通过该模型调用
save()或create()的新增操作才会触发
⚠️ 注意：在控制器里 new Model() 后直接 save($data)，若模型尚未加载或 init() 未执行，事件也不会触发。确保模型已被完整初始化。
立即学习“PHP免费学习笔记（深入）”；
参数与数据操作方式
onBeforeInsert 接收一个参数：$data，它是即将写入的数据数组（非对象实例）。你可以修改这个数组来影响最终入库内容：
- 给字段赋值：
$data['create_time'] = date('Y-m-d H:i:s'); - 处理业务字段：
$data['create_by'] = session('user_id') ?: 0; - 加密敏感字段：
$data['password'] = md5($data['password'] . config('salt')); - 返回
false可中断插入流程（适合权限拦截或强校验）
⚠️ 不要尝试用 $this->xxx = xxx 赋值——此时模型实例尚未创建完成，$this 不可用；所有操作必须作用于传入的 $data 数组。
常见失效原因排查
如果写了 onBeforeInsert 却没反应，优先检查以下几点：
- 是否用了
save(['field' => 'val'])直接传数组？这会跳过自动填充和事件。应改用model->data($data)->save() - 是否启用了严格模式（
'strict' => true）且$data中包含未定义字段？字段会被静默丢弃 - 是否在调试模式（
APP_DEBUG = true）下测试？非调试模式下事件异常可能被静默捕获 - 是否确认调用的是模型的
save()，而不是Db::insert()？后者完全绕过模型事件
