PHP Enum 映射数据库值的类型安全方案

PHP Enum 映射数据库值时，推荐使用 Backed Enum：数据库保存稳定的 string 或 int 标量，业务层把它转换成枚举 case，边界处再用 tryFrom() 或 from() 明确处理未知值。这样既不会把数据库字符串散落在业务代码里，也不会把非法状态悄悄当成正常数据。

官方文档：https://www.php.net/manual/en/language.enumerations.backed.php

先确定数据库标量与 Enum case 的一一对应关系

迁移前先看表里的真实值，而不是先写 enum。假设订单表的 status 字段保存 pending、paid、cancelled，它们是协议值；待支付、已支付只是界面文案。case 名称可以按 PHP 命名习惯写，真正需要稳定的是右侧的 backed value。

如果字段是整数，就定义 enum OrderStatus: int；不要为了省一次转换，把整数列和字符串 enum 混在一起。

用 Backed Enum 固定可持久化值

下面的 enum 把持久化协议集中到一个地方。方法返回类型使用 self，调用方拿到的就不再是任意字符串。

这里的重点不是把字符串换成更长的写法，而是把“允许值”变成可被 IDE、静态分析和函数签名共同约束的类型。新增状态时，业务分支会更容易被搜到。

在读取边界选择 tryFrom 或 from

tryFrom() 找不到对应值会返回 null，适合数据库、请求参数或旧系统同步来的不完全可信数据。from() 找不到值会抛出 ValueError，适合前面已经完成约束的内部流程。两者都不能替代数据治理：如果未知值频繁出现，应记录原值、主键和来源，避免用默认 case 掩盖脏数据。

不要只写 (string)$row['status'] 后直接调用 from()。强制转换可能把 null 或错误类型包装成看似合法的字符串，问题会被推迟到业务深处。

保存与输出时只交换 scalar value

读取时是“标量进、case 出”，写回时反过来：把 $status->value 交给 PDO 或 ORM。API 返回 JSON 时，Backed Enum 会以其标量值表达；为了让接口协议更直观，也可以在 DTO 映射处显式写出 value。

 $status->value];
}

$status = OrderStatus::Paid;
$params = statusForUpdate($status);
// 真实项目中将 $params 绑定到 UPDATE ... SET status = :status。

case 名称是代码内部标识，数据库协议是 value。因此重命名 Paid 为 Settled 时，只要 backed value 仍是 paid，存量数据和接口协议就不会因为命名调整而改变。

迁移前用清单验证旧数据和回归边界

把旧字段接入 Enum，最容易遗漏的是历史脏值和大小写差异。上线前至少完成以下检查：

• 统计 status 的 distinct 值，逐个映射到 case；
• 确认数据库驱动返回的是字符串还是整数，并与 enum backed type 一致；
• 为缺失值、未知值和新增 case 分别写测试，不用同一个默认值吞掉三种情况；
• 检查写回路径只使用 ->value，不要把 case 名称持久化；
• 记录未知原值和记录标识，修复数据后再扩大读取范围。

完成这份清单后，Enum 才真正成为数据库边界的类型安全层，而不是一组换了写法的常量。

相关问题

数据库里的空值可以直接映射成 Enum 吗？

不能直接映射。先决定字段是否允许 null，再使用 ?OrderStatus 返回类型和单独的空值策略；不要把空值伪装成某个正常 case。

from() 和 tryFrom() 该怎么选？

可信且已校验的内部值可用 from()；数据库、请求和旧系统数据优先用 tryFrom()，让调用方决定记录、降级还是拒绝。

修改 Enum case 名称会影响数据库吗？

只要 backed value 不变，数据库中的标量不会改变；但序列化、日志和代码引用仍需回归检查。