PHP enum 输出 JSON 时如何固定 backed value

PHP enum 要稳定输出 JSON，关键不是在 json_encode() 外面再包一层转换，而是把枚举声明为 backed enum，并给每个 case 写死唯一的 string 或 int 值。这样，接口序列化时会直接得到这个 value；接收请求时再用 from() 或 tryFrom() 把标量还原成 case。

官方地址：https://www.php.net/manual/en/language.enumerations.serialization.php

先把 enum 定义成有标量值的 backed enum

例如订单状态需要落库、传给前端或进入消息队列时，可以把接口契约固定为小写字符串。不要依赖 case 名称自动推导 value，PHP 不会替你生成连续数字。

同一个 enum 只能选择一种 backed 类型；如果声明为 int，所有 case 都必须使用整数。两个 case 不能共享同一个标量值，否则定义阶段就会失败。

默认 json_encode 如何保持 value 类型

backed enum 不需要额外实现接口，直接放进数组或对象属性即可。字符串 backed enum 输出 JSON 字符串，整数 backed enum 输出 JSON 数字。

 1024,
    'status' => PaymentStatus::Paid,
];

// JSON_THROW_ON_ERROR 让序列化失败变成异常，避免静默得到 false。
$json = json_encode($payload, JSON_THROW_ON_ERROR);
echo $json;

{"order_id":1024,"status":"paid"}

这里的 paid 来自 PaymentStatus::Paid->value，不是字符串 Paid。如果业务要求数字协议，就声明 enum PaymentStatus: int 并给出明确整数；不要在序列化前临时把不同类型拼在一起。

接收 JSON 时用 from 还是 tryFrom

输出固定 value 只是半程。读回请求或数据库字段时，from() 找不到 value 会抛出 ValueError，适合已通过约束的内部数据；tryFrom() 找不到时返回 null，更适合用户输入或旧数据兼容。

value;

若输入来自内部白名单，也可以写 PaymentStatus::from($rawStatus)，让异常尽早暴露。两种方法都不会把未知字符串“猜成”某个 case。

需要对象结构时再实现 JsonSerializable

如果前端不仅要 value，还要显示名、颜色或是否终态，别把默认 backed value 和自定义响应混为一谈。枚举可以实现 JsonSerializable，明确返回一个数组；这会覆盖默认的标量序列化行为。

 $this->value,
            'label' => match ($this) {
                self::Pending => '待支付',
                self::Paid => '已支付',
                self::Cancelled => '已取消',
            },
        ];
    }
}

只需要机器可读状态时，保留默认 backed value 更简单；需要复合对象时，才用 JsonSerializable，并为新增字段补充接口兼容策略。

常见问题

为什么输出的是 value，不是 case 名称？

这是 backed enum 的默认 JSON 规则。名称是 PHP 代码标识，value 才是你显式定义的传输标识。

可以让一个 enum 同时有字符串和整数 value 吗？

不可以。一个 backed enum 只能选择 string 或 int 一种类型。

pure enum 怎么传给前端？

纯 enum 不能直接 JSON 化；可以改成 backed enum，或在 DTO 映射层显式返回名称和业务值。

未知 value 应该返回哪个状态？

不要静默猜测。用 tryFrom() 得到 null 后返回校验错误，只有业务明确允许默认值时才做降级。