PHP 枚举 backed value 与数据库字段映射方案

PHP 8.1 引入枚举后，订单状态、支付状态、审核结果这类“只能取有限值”的字段不必继续散落字符串。需要落库时，优先使用 backed enum：枚举负责约束业务代码，value 负责和数据库交换标量。完整流程可以概括为：先固定字段契约，再用 $enum->value 写入，读取时根据数据可信度选择 from() 或 tryFrom()。

数据库保存的是 backed enum 的 value，而不是枚举对象或 case 名称。可信数据用 from() 让异常尽早暴露；可能来自旧数据、人工修复或外部导入的值用 tryFrom()，把未知值交给明确的兜底策略。

先确定字段和枚举的边界

PHP 官方把 backed enum 定义为带有 string 或 int 标量等价物的枚举，同一个枚举不能同时使用两种 backing type。每个 case 都必须显式定义唯一的 value，因此数据库字段的类型和取值集合应该先写成契约。

例如订单状态适合保存为字符串：

value; // paid

对应数据库可以使用 VARCHAR 或等价的字符串类型，并预留项目需要的长度。若使用 int backed enum，则字段也按整数设计，读取时不要把它当作字符串常量。不要用 name 代替 value：前者是代码中的 case 名称，后者才是定义好的外部标量。

把 value 作为唯一写入出口

写入时不要把 OrderStatus::Paid 这个对象直接绑定给 PDO。统一在仓储或数据访问边界取出 value，这样 SQL 层只接收字符串或整数，领域层仍然保留枚举类型。

prepare($sql);

    // value 的类型来自 enum 定义，id 则明确绑定为整数。
    $statement->bindValue(':status', $status->value, PDO::PARAM_STR);
    $statement->bindValue(':id', $orderId, PDO::PARAM_INT);
    $statement->execute();
}

这层的检查点有三个：字段类型与 backing type 一致；SQL 参数只接收 value；新增 case 时同步评估数据库约束、索引和下游报表。若业务允许“没有状态”，先决定是可空字段还是额外的 Unknown case，不要让空字符串悄悄承担两种含义。

读取时选择 from 还是 tryFrom

数据库返回的是标量，恢复枚举要根据数据来源判断。from() 找不到匹配值会抛出 ValueError，适合已经经过约束、迁移和应用控制的数据；tryFrom() 找不到匹配值返回 null，适合历史数据、人工导入或边界接口。

如果采用默认状态，必须确认默认值不会掩盖数据损坏。例如只有“展示层允许降级”时才可以写成 OrderStatus::tryFrom($raw) ?? OrderStatus::Pending；订单结算、权限判断等关键路径更适合返回错误并记录原始值。

迁移、查询和常见误区

迁移顺序：先确认旧字段中的值，再补齐枚举 case；必要时先清洗脏值，再启用数据库约束；最后把读写代码切换到统一映射。不要先删除旧值，否则 from() 可能在发布后集中抛错。

查询条件：查询仍然使用 $status->value 作为参数，而不是把枚举名称拼进 SQL。列表筛选可以先把多个枚举对象映射成 value 数组，再用占位符绑定，避免字符串拼接。

类型误区：在 declare(strict_types=1) 下，字符串 backed enum 与整数输入的转换边界更严格；不要依赖隐式转换来修复字段类型。from() 和 tryFrom() 接受的是标量，不接受枚举对象本身。

ORM 边界：如果框架或 ORM 已提供 enum cast，仍然要确认它保存的是 value，并核对 null、未知值和批量更新行为。本文的核心契约独立于 ORM：领域对象使用 enum，持久化边界使用 scalar。

一张表记住映射方案

最小原则只有一句：让 enum 的 value 成为数据库契约，让读取入口表达数据可信度。这样新增状态、修复历史数据或更换 ORM 时，变化都会集中在边界层，而不会扩散到业务判断。

相关问题

PHP backed enum 可以同时保存字符串和整数吗？

不可以。同一个 backed enum 只能选择 string 或 int 其中一种 backing type；需要两种外部表示时，应拆成不同枚举或在边界层做明确转换。

数据库里应该保存 case 名称还是 value？

通常保存定义好的 value。它是专门为序列化和数据库往返准备的标量；case 名称更偏向代码内部命名，重命名时不应无意改变数据契约。

什么时候应该用 tryFrom？

当值可能来自旧版本、人工导入、第三方接口或用户输入时使用。返回 null 后要继续做记录、拒绝、默认或修复队列等业务决策，不能把 null 静默吞掉。

参考：PHP Backed enumerations、BackedEnum::from、BackedEnum::tryFrom。