PHP enum JSON 序列化为什么输出值而不是名称

PHP 的 backed enum 直接交给 json_encode() 时，默认输出的是 backing value，不是 case 名称。比如 OrderStatus::Paid 的名称是 Paid，值是 paid，JSON 结果会是字符串 "paid"。这不是名称丢失，而是 PHP 把 backed enum 设计成可直接往数据库或接口传递的标量。

如果接口契约要传数据库值，就直接序列化 backed enum；如果契约要展示名称或同时返回名称和值，就明确写出转换结构。

为什么 backed enum 默认输出 value

一个 backed enum 同时拥有两层信息：case 的名字用于代码阅读，backing value 用于稳定存储和传输。PHP 官方文档规定，backed enum 的 JSON 表示是它的标量值，并保持对应的字符串或整数类型。因此下面的 json_encode() 并不会尝试输出 Paid：

name, PHP_EOL;                    // Paid
echo $status->value, PHP_EOL;                   // paid
echo json_encode($status, JSON_THROW_ON_ERROR); // "paid"

这里的三个结果并不矛盾：name 是枚举声明中的标识符，value 是显式定义的 backing scalar，而 JSON 默认选择后者。值还可以通过 OrderStatus::from('paid') 找回对应 case；面对外部输入时，优先使用 tryFrom() 并处理返回的 null。

pure enum 和 backed enum 不能混着理解

pure enum 只有 case 对象，没有内置的字符串或整数值。它可以正常参与 PHP 自己的序列化，但直接转 JSON 时没有默认的标量表示；backed enum 则因为有明确的 string 或 int 值，可以直接输出对应标量。

所以，看到接口返回 "paid" 时，不要先把它判断成序列化错误。先问清楚接口字段表示的是稳定业务值，还是面向人的显示名称。两者确实都要返回时，再把输出结构写出来。

需要输出名称时怎么改成显式结构

最简单的做法是在 DTO 或响应组装处显式读取 name 和 value。如果多个接口都需要相同规则，可以让枚举实现 JsonSerializable，把序列化契约集中在 enum 内部：

 $this->name,
            'value' => $this->value,
        ];
    }
}

echo json_encode(OrderStatus::Paid, JSON_THROW_ON_ERROR);
// {"name":"Paid","value":"paid"}

这种写法改变的是 JSON 契约，不是 enum 的内部值。前端若只需要下拉选项的值，返回 "paid" 更简单；若还要显示人类可读文案，可以把 label 作为单独字段加入 DTO，而不是让前端猜测 case 名称。

落地时检查这几个兼容边界

• 先确认数据库存的是 value，还是另有展示字段；不要用 name 代替已有持久化值。
• 对请求参数使用 tryFrom() 时处理 null；可信内部值才适合让 from() 在异常时中断。
• 给接口写测试断言，明确断言字符串、整数还是对象，避免只断言“能转 JSON”。
• 一旦实现 JsonSerializable，所有直接序列化这个 enum 的调用方都会看到新结构，要把它当作接口变更管理。

相关问题

PHP enum 的 name 和 value 有什么区别？

name 是 case 标识符，例如 Paid；value 是 backed enum 声明的字符串或整数，例如 paid。默认 JSON 使用 value。

为什么 json_encode pure enum 会失败？

pure enum 没有内置标量值，PHP 没有默认的 JSON 表示。可以先把它转换为自定义数组，或实现 JsonSerializable。

怎样把字符串安全转回 backed enum？

外部输入使用 tryFrom($value) 并检查 null；必须视为非法数据时再使用 from($value)，让无匹配值抛出 ValueError。