PHP 枚举序列化到接口字段的映射方式

PHP 8.1+ 中，接口字段需要传输字符串或整数时，优先使用 backed enum 固定协议值：响应侧把枚举放进数组或 DTO，json_encode() 会输出它的 backing value；请求侧再用 tryFrom() 把外部值映射回枚举。这样 case 名称留在领域代码里，接口只暴露稳定的值。纯枚举没有标量值，不能直接当作 JSON 字段使用。

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

最稳妥的边界是“backed enum 负责合法值集合，DTO 负责接口字段形状，tryFrom 负责不可信输入”。只有接口确实需要同时返回编码和展示名称时，才显式实现 JsonSerializable。

先把枚举的接口值固定下来

不要把 Pending 这样的 case 名称直接当成接口协议。给每个 case 明确的字符串或整数值，数据库、消息和 HTTP 响应都围绕这个值协作。PHP 官方把这种枚举称为 backed enum；同一个枚举只能选择 int 或 string 其中一种 backing type，且每个 case 的值必须唯一。

value; // paid
?>

这里的 OrderState::Paid 是枚举对象，OrderState::Paid->value 才是接口字段要传输的字符串。不要依赖“自动生成数字值”，backed enum 不会替你按顺序生成 backing value。

响应字段让 json_encode 自然输出标量

backed enum 放入数组、对象属性或实现了公开字段的响应 DTO 后，JSON 序列化会使用它的标量值。推荐先在响应对象中确定字段形状，再统一调用 json_encode()；这样调用方看到的是 "status":"paid"，而不是 PHP 内部的枚举类结构。

 1001,
    'status' => OrderState::Paid,
];

// JSON_THROW_ON_ERROR 让编码失败立即变成异常，便于接口层统一处理。
$json = json_encode($response, JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);
echo $json;
// {"id":1001,"status":"paid"}
?>

如果接口需要整数编码，也可以声明 enum OrderState: int。关键不是选择字符串还是整数，而是从一开始固定协议类型，并让数据库列、请求校验和响应字段使用同一组值。

请求字段回填时用 tryFrom 做边界处理

请求参数、数据库旧数据和消息队列内容都属于外部输入。tryFrom() 找不到匹配值时返回 null，适合把“未知状态”转成明确的 400 响应或业务默认值；from() 找不到值时会抛出 ValueError，更适合已经经过可信校验的内部数据。

不要用 (OrderState)$raw 做强制转换，也不要把未知值静默改成 Paid。默认值只有在业务明确允许时才应使用，并且要能区分“请求省略字段”和“请求传入了未知字段”。

需要复合字段时显式实现 JsonSerializable

默认的 backed enum JSON 表示是一个标量。如果前端同时需要 code、name 和展示文本，就不要期待序列化器自动猜出字段，而是在枚举或 DTO 中实现 JsonSerializable。这样协议形状由代码明确控制，也方便未来增加字段。

 '待支付',
            self::Paid => '已支付',
        };
    }

    public function jsonSerialize(): array
    {
        // 复合 JSON 结构必须显式列出字段，避免暴露无关内部属性。
        return [
            'code' => $this->value,
            'name' => $this->name,
            'label' => $this->label(),
        ];
    }
}

echo json_encode(OrderState::Paid, JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);
// {"code":"paid","name":"Paid","label":"已支付"}
?>

如果只有一个 status 字段，保留默认标量序列化更简单；只有在接口契约明确要求复合对象时才定制输出。纯 enum 若直接传给 json_encode() 会失败，也应改成显式 DTO 或实现 JsonSerializable。

回滚路径、告警确认与复盘项

把旧字符串字段迁移为 backed enum 时，先保留旧值读取能力，再切换写入逻辑。回滚时让 DTO 继续输出旧协议值，避免只回滚 PHP 代码却让数据库或客户端读到新 case。发布后重点观察三类信号：

• 输入校验：tryFrom() 返回 null 的比例，区分客户端传错和历史脏数据。
• 编码异常：接口层是否出现 JsonException，特别是纯 enum 或自定义序列化返回非法值的情况。
• 协议兼容：客户端是否把 status 当字符串或整数处理，是否错误依赖 case 名称。

复盘时记录“字段原值、允许的 backing value、未知值处理、默认策略和回滚版本”五项即可。这样枚举不只是语法糖，而是把输入、领域对象和接口字段之间的边界固定下来。

常见问题

纯 enum 为什么不能直接 JSON 序列化？

纯 enum 没有 backing value，PHP 无法自动决定应输出哪个标量。需要实现 JsonSerializable，或在 DTO 中把它转换为明确的字符串字段。

接口传入未知值时应该用 from 还是 tryFrom？

外部请求优先用 tryFrom()，由业务返回可读的 400 错误；已经确认合法的内部值才使用 from()，让不可能的状态直接抛出异常。

能不能直接把 case 名称作为接口值？

可以，但不建议把实现名称当协议。使用显式 backing value 能让代码重命名 case 时保持接口兼容，也能让数据库和消息中的值更稳定。