PHP如何加密Eloquent属性 Laravel字段保护教程

本文深入解析了 Laravel Eloquent 字段级加密的核心机制与实战陷阱：必须严格通过 `$casts` 声明 `'encrypted'` 或 `'encrypted:array'` 才能生效，任何中间件或手动加密都无法替代；加密数据不可查询、依赖未轮换的 `APP_KEY` 且需 `TEXT` 字段存储；一旦密钥变更将导致历史数据永久无法解密；同时警示常见错误——如错误声明类型、在 `where()` 中直接查询加密字段、忽略序列化时的明文泄露风险，以及关系加载和 API 输出中的隐蔽安全隐患——真正考验开发者的不是加密本身，而是对安全边界、生命周期和工程细节的系统性把控。

加密字段在 Eloquent 中必须定义为 $casts 且类型为 encrypted

不加 $casts 声明，哪怕用了 encrypt 中间件或手动调用 Crypt::encrypt()，Laravel 都不会自动加解密该属性。Eloquent 的字段级加密只通过 $casts 生效，且仅支持 'encrypted' 和 'encrypted:array' 两种字符串值。

常见错误是误写成 'encrypted_string' 或 'encrypt'，这会导致静默失败——存进去的是明文，读出来也是明文，毫无加密效果。

• $casts = ['api_token' => 'encrypted']：适用于字符串、整数、布尔等基础类型
• $casts = ['meta' => 'encrypted:array']：自动序列化/反序列化后再加解密
• 数据库字段类型建议用 TEXT（而非 VARCHAR(255)），因为加密后数据长度明显增长（Base64 编码 + IV + MAC）

Crypt 驱动必须启用且 APP_KEY 未被轮换

Eloquent 加密底层依赖 Illuminate\Encryption\Encrypter，它严格绑定当前 APP_KEY。一旦更换 APP_KEY，所有已加密字段将无法解密，decrypt() 抛出 DecryptException 错误，典型提示是 The payload is invalid.。

这不是 bug，是设计使然——加密不是为了“可迁移”，而是“防数据库泄露”。所以生产环境切勿随意重置 APP_KEY；若必须轮换，需自行实现渐进式解密再加密的迁移逻辑。

• 检查是否启用：config('app.cipher') 必须为 'AES-256-CBC'（默认值，不要改）
• 确认 APP_KEY 在 .env 中存在且长度为 32 字符（php artisan key:generate 生成）
• 运行 php artisan tinker 测试：Crypt::encrypt('test') 不报错即驱动可用

不能在查询构建器中直接 where() 加密字段

加密字段内容在数据库中是随机字符串（每次加密结果不同），因此 ->where('api_token', 'xxx') 永远查不到数据。Eloquent 不提供服务端解密查询能力，这是安全前提决定的。

真实场景中，需要查加密字段时，只有两种可行路径：

• 先用明文条件查出主键（比如用户登录时用邮箱查 User），再在模型实例上调用属性访问（$user->api_token 自动解密）
• 对极少数需索引的敏感字段（如手机号），改用确定性加密（如 HMAC-SHA256 哈希+盐）并单独建索引字段，但这就脱离了 Eloquent 内置加密机制
• 避免在 select() 中裸写加密字段名，否则会触发自动解密并可能暴露日志（尤其开启 query log 时）

关系模型中加密属性不会自动穿透，需显式加载

如果 Post 属于 User，而 User::$casts = ['ssn' => 'encrypted']，那么 Post::with('user')->get() 返回的 $post->user->ssn 是解密后的值 —— 这没问题。但若用延迟加载：$post->user->ssn 第一次访问时才解密，此时若 $post->user 是懒加载（lazy eager loading）且未加 with()，就可能触发 N+1 查询 + 解密开销。

更隐蔽的问题是：加密属性在 toArray() 或 JSON 序列化时**默认仍保持解密状态输出**，除非你主动禁用：

• 全局屏蔽：protected $hidden = ['ssn'] 或 protected $casts = ['ssn' => 'encrypted:array'] 并配合 toJson() 时注意结构
• 临时屏蔽：$user->makeHidden(['ssn'])->toArray()
• 别在 API 资源类里直接 $this->resource->ssn，应改用 $this->when($this->resource->hasEncryptedAttribute('ssn'), [...]) 控制输出

真正麻烦的从来不是怎么加解密，而是记住哪些字段被加密了、在哪次序列化中漏掉了隐藏、以及 APP_KEY 变更后那堆无法恢复的数据。

今天关于《PHP如何加密Eloquent属性 Laravel字段保护教程》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！