PHP enum 序列化到 JSON 时如何保持稳定接口值

日常写PHP接口用枚举做常量约束的时候，不少人都遇到过直接序列化JSON返回的结果和约定的接口值对不上的问题，有时候返回枚举名，有时候返回整个对象结构，调用方直接解析报错。

PHP 枚举要在序列化到JSON时始终输出稳定的接口约定值，直接给目标枚举实现JsonSerializable接口是最稳妥的方案，不用改全局配置也能兼容不同调用场景。

PHP enum 放进 JSON 接口时，稳定性取决于你把哪一个值当成契约。对于 enum Status: string 这类 backed enum，json_encode() 默认输出它的 backed value，例如 "paid"，不会输出 case 名 Paid。如果接口只需要一个机器值，这正是最简洁的方案；如果还要返回 code、label 等字段，就应实现 JsonSerializable，把响应结构显式固定下来。

backed enum 默认输出的是 value，不是 case 名

先看最常见的接口字段。case 名是 PHP 代码中的标识，适合开发者阅读；value 才是可以写入数据库、传给前端并长期保持不变的外部值。官方序列化规则规定，backed enum 编码为对应的标量值，并保留字符串或整数类型。

 OrderStatus::Paid];
echo json_encode($payload, JSON_UNESCAPED_UNICODE);
// {"status":"paid"}

因此，后续把 Paid 改成 PaymentReceived，只要 'paid' 不变，接口值就不会跟着变。相反，如果直接改 backed value，数据库筛选、缓存键和前端判断都可能受到影响，这应当按接口变更处理。

纯 enum 为什么不能直接编码成 JSON

没有 backed value 的纯 enum 只有 case 名，没有一个内置的外部标量。下面的类型不应直接塞进响应：

 Visibility::Public]);
var_dump($json, json_last_error_msg());
// false，通常会得到 “Non-backed enums have no default serialization”

如果业务确实要传出它的名字，应当显式选择 ->name，并把这个选择写进接口文档；更推荐为对外协议定义 backed enum，而不是让消费者猜测内部 case 名。

需要 code、label 等字段时用 JsonSerializable 显式建模

单一字符串适合筛选和提交，但列表页往往还需要展示文案。此时不要在控制器里到处拼数组，可以让 enum 自己声明稳定的 JSON 形状：

 '已支付',
            self::Shipped => '已发货',
        };
    }

    public function jsonSerialize(): array
    {
        return ['code' => $this->value, 'label' => $this->label()];
    }
}

echo json_encode(['status' => OrderStatus::Paid], JSON_UNESCAPED_UNICODE);
// {"status":{"code":"paid","label":"已支付"}}

实现后，默认的标量输出会被覆盖，所以前端必须按对象读取。若同一个 enum 同时被多个接口复用，建议确认所有调用方都接受这个结构；否则可以在资源转换层返回对象，把 enum 本身继续保留为标量契约。

用固定 value 和 JSON 断言守住接口兼容

稳定接口不是“今天能编码”就够了，还要防止重构时悄悄改变输出。至少锁定三件事：case 的 backed value、JSON 字段类型、是否返回对象。测试可以直接断言最终字符串或解码后的数组：

 OrderStatus::Paid], JSON_UNESCAPED_UNICODE),
    true,
    512,
    JSON_THROW_ON_ERROR
);

assert($actual['status']['code'] === 'paid');
assert($actual['status']['label'] === '已支付');

发布前还应检查输入端是否用 OrderStatus::tryFrom($value) 处理未知值：新值到来时返回空值并走业务分支，比直接强制转换抛错更容易做兼容策略。最终选择可以归纳为：只传机器值就使用 backed enum 默认编码；需要附加信息就显式实现 JsonSerializable；永远不要把未约定的 case 名当成稳定协议。

相关问题

PHP enum 的 value 可以改吗？可以，但对外接口和持久化数据中的 value 应视为兼容契约，改动前要做迁移和版本评估。

JsonSerializable 能返回字符串吗？可以，jsonSerialize() 返回任何可被 json_encode() 编码的值；返回数组时才会形成 code、label 这样的对象结构。

参考：PHP Enumerations Serialization、JsonSerializable::jsonSerialize。事实核对时间：2026-09-07。