PHP 枚举序列化JSON 输出枚举值时为什么格式不一致为什么结果为空或不符合预期

PHP 枚举的 JSON 形状取决于枚举类型和自定义序列化：字符串支撑枚举默认输出字符串，整数支撑枚举默认输出整数；纯枚举没有默认 JSON 表示，编码会失败；实现 JsonSerializable 又可以改变这些默认行为。结果看起来为空时，应先暴露编码错误，再讨论接口格式。

PHP 官方地址：https://www.php.net/

如果我要把一个状态字段从字符串迁移到枚举，我会先保留原接口的标量形状，再决定是否增加对象字段。这里用一组原创的迁移推演说明这个取舍，不把示例写成已经发生的项目经历或本机测试结果。

先分清纯枚举、字符串枚举和整数枚举

旧接口的 state 可能一直是字符串 ready。改成枚举后，开发者看到调试输出中的 name 与 value，就容易以为 JSON 也会自动包含这两个属性。枚举的默认 JSON 规则与普通对象不同，不能根据 print_r、var_dump 或数据库里看到的样子推断响应格式。

Pure Enum 对应没有支撑标量值的纯枚举；Backed Enum:string 与 Backed Enum:int 分别对应字符串和整数。json_encode 是编码接口：前者默认触发编码错误，后两者使用各自标量。类型不是格式装饰；数字 1 与字符串“1”对调用方是两种不同的 JSON 值。

先把失败显式化，再比较默认输出

下面示例要求 PHP 8.1 及以上，保存为 enum_json.php。三个枚举故意使用不同名字，方便同时比较。JSON_THROW_ON_ERROR 让错误进入异常分支，不用一个空响应掩盖编码失败。

 $state->value];
}

echo json_encode(apiPayload(ApiState::Ready), JSON_THROW_ON_ERROR), PHP_EOL;
echo json_encode(['state' => NumericState::Ready], JSON_THROW_ON_ERROR), PHP_EOL;

try {
    // 纯枚举没有默认 JSON 标量表示，显式抛异常以免空响应掩盖失败
    echo json_encode(['state' => PlainState::Ready], JSON_THROW_ON_ERROR);
} catch (JsonException $error) {
    fwrite(STDERR, 'JSON 编码失败：' . $error->getMessage() . PHP_EOL);
}

// 纯枚举可以显式映射名称；是否采用名称作为协议值必须事先约定
echo json_encode(['state' => PlainState::Ready->name], JSON_THROW_ON_ERROR), PHP_EOL;

按语言规则推导，前三个成功输出依次应包含字符串 ready、数字 1 和字符串 Ready；纯枚举那次应进入异常分支。这里没有执行代码，错误的完整文案也不作为跨版本协议使用。标准错误输出与标准输出属于不同通道，实际展示顺序不应用来判断业务执行顺序。

若不使用抛异常标志，json_encode 失败可能返回 false；直接 echo false 看起来就像没有内容。不要把它等同于合法 JSON 的 null，也不要盲目设置部分输出选项来忽略失败。先处理错误，才能知道哪些字段没有成功编码。

把输出形状固定在接口边界

我更倾向于先用 apiPayload 显式提取 ApiState 的 value，再构造 state 字段。这样领域内部可以使用枚举，而接口仍保持原有字符串契约。name 是 case 名称，value 才是该支撑枚举声明的值；二者碰巧相似时，最容易把问题带到下一次重命名。

第二种选择是让枚举实现 JsonSerializable，通过 jsonSerialize 定义形状：

 $this->value, 'name' => $this->name];
    }
}
echo json_encode(['state' => DisplayState::Ready], JSON_THROW_ON_ERROR);

此时 state 是含 code、name 的对象，不能再要求调用方把它当作简单字符串。这种设计适合所有使用者都需要统一对象表示的场景；同一枚举服务多个接口、后台任务或第三方集成时，我会把协议差异留在各自的映射层，避免全局改变枚举的默认形状。

迁移前后需要保持什么兼容性

数组键不连续造成 JSON 列表变对象，是容器形状问题，不是枚举标量规则改变。框架资源层或序列化器也可能提前把枚举转换成数组；出现“同一个枚举两个接口形状不同”时，要比较进入 json_encode 前的数据，而不是只看枚举定义。

本例不改变数据库值、不反序列化外部对象，也不读取用户输入。实际迁移要明确未知状态如何处理，不能把所有未知值默认映射到 Ready，否则格式统一了，业务含义反而错了。

为什么 serialize 的结果与 JSON 完全不同

PHP 原生 serialize 为枚举保存的是可恢复 case 身份的内部格式，JSON 是跨语言数据协议。不要把原生序列化字符串直接作为前端状态字段，也不能期待 json_decode 自动恢复枚举实例。支撑枚举的恢复需在输入边界按已知类型和允许值显式处理。

什么时候值得自定义 JsonSerializable

当枚举自身确实有稳定、统一、跨所有调用者的 JSON 形状时可以使用。仅某个页面需要 code 加显示名时，接口映射通常更直观，也更容易保持旧消费者兼容。字符串、对象哪种更好没有统一答案，先固定消费者真正需要的协议。

官方枚举序列化规则：https://www.php.net/manual/en/language.enumerations.serialization.php；自定义接口：https://www.php.net/manual/en/jsonserializable.jsonserialize.php；JSON 编码错误与选项：https://www.php.net/manual/en/function.json-encode.php。