PHP 枚举实现接口时的序列化边界

我第一次把 PHP 枚举接进接口层时，误以为“实现了接口”就等于“序列化格式也定下来了”。代码在类型检查上很漂亮：服务只依赖接口，枚举 case 也能直接传入；可一到缓存、消息和 JSON 响应，数据却出现了三种完全不同的形状。

后来我把这件事拆成四个边界，问题才变简单：业务接口约束行为，原生 serialize() 保存枚举身份，JsonSerializable 定义 JSON 输出，输入适配器负责从标量恢复枚举。它们可以由同一个枚举参与，但绝不是同一份契约。

官方依据：https://www.php.net/manual/en/language.enumerations.methods.php、https://www.php.net/manual/en/language.enumerations.serialization.php

接口只是行为契约，不是序列化协议

PHP 允许纯枚举和有值枚举实现接口。这样做最适合表达稳定行为，例如展示文案、权限判断或状态分组。只要一个 case 属于实现该接口的枚举，它就能通过对应的接口类型检查。

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

function renderLabel(DisplayLabel $state): string
{
    // 调用方只关心接口行为，不关心枚举怎样编码
    return $state->label();
}

这段代码解决的是“哪些对象能提供标签”，并没有回答“写入缓存时保存什么”“接口响应返回字符串还是对象”。如果把接口名写成 SerializableState，也不会自动改变 PHP 的编码规则；真正的格式仍由具体序列化通道决定。

原生 serialize 保存的是类型和 case 名

PHP 官方文档说明，枚举使用专门的 E 序列化代码，其中记录枚举类型与 case 名。反序列化时，PHP 会找到已经存在的那个单例 case，而不是创建一个带属性的新对象。因此同一个 case 往返后仍保持严格相同。

这个格式的优点是能保留“这是哪个枚举的哪个 case”，代价则是与 PHP 类型名和 case 名绑定。重命名 OrderState、移动命名空间或把 Paid 改名，都可能让历史字符串无法找到对应枚举；官方文档指出，此时反序列化会发出警告并返回 false。

这里还有一个容易忽略的边界：unserialize() 的 allowed_classes 选项不影响枚举。不要把它当成枚举白名单，更不要用原生反序列化处理不可信输入。原生格式更适合生命周期明确、生产者和消费者一起部署的内部数据。

JsonSerializable 只负责 JSON 输出

如果 OrderState 不实现 JsonSerializable，作为字符串 backed enum 交给 json_encode() 时，默认就是它的标量值，例如 "paid"。对多数 API 来说，这反而是最稳定、最省事的契约。

只有当接口确实需要同时返回机器值和展示文案时，我才会让枚举实现 JsonSerializable：

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

    public function jsonSerialize(): array
    {
        // JSON 合同显式固定为 value 与 label 两个字段
        return [
            'value' => $this->value,
            'label' => $this->label(),
        ];
    }
}

jsonSerialize() 可以返回任何能被 json_encode() 原生处理的值。这里选择关联数组后，JSON 形状就从字符串变成了对象。这个变化可能让旧客户端直接失效，所以不能只把它视为“多加一个接口”；它是公开数据协议的变更。

纯枚举没有 backing value，默认 JSON 编码会报错。此时实现 JsonSerializable 很有价值，可以明确返回 $this->name 或稳定的自定义字符串。但一旦对外发布，就要像维护 API 字段一样维护这些值，避免随代码重命名而漂移。

把反向恢复放在输入适配层

JsonSerializable 没有定义 JSON 反序列化方法。json_decode() 也不会根据返回类型自动把字符串变回枚举。对外部请求、消息和数据库字段，我更倾向于先解析标量，再在适配层调用 backed enum 自带的 from() 或 tryFrom()。

受信任且“不存在就应立即失败”的内部值可以使用 from()，它在没有匹配 case 时抛出 ValueError。外部输入通常更适合 tryFrom()，因为应用可以把 null 转成自己的校验错误、HTTP 422 或消息拒绝原因。

两个看似省事的反例

让一个接口同时承担行为和传输格式

如果业务层看到 DisplayLabel 就默认对象一定能编码为 {value,label}，调用方实际上依赖了接口没有声明的事实。以后另一个普通类实现同一接口，序列化形状就可能不同。更稳妥的方式是让业务代码依赖行为接口，让 API 资源、响应 DTO 或明确的 JsonSerializable 负责输出格式。

把 case 名直接当长期外部标识

$case->name 很方便，但它往往更接近代码标识；$case->value 才适合作为经过设计的外部值。若已经把 case 名发布给客户端，后续重命名就不仅是内部重构。对于 backed enum，建议把稳定的小写字符串放在 value，展示文案通过方法提供。

采用前的判断清单

常见问题

枚举实现 JsonSerializable 后会改变 serialize() 的结果吗？

不会。JsonSerializable 控制的是 json_encode()。PHP 原生 serialize() 仍使用枚举专用的 E 表示，保存枚举类型和 case 名。

backed enum 一定要实现 JsonSerializable 吗？

不一定。默认情况下，它会编码成对应的字符串或整数标量。只有契约需要其他形状时才实现，并把形状变化当成 API 兼容性决策。

json_decode 能自动恢复枚举吗？

不能。先解码 JSON，验证字段类型，再用 from() 或 tryFrom() 显式映射。

为什么不直接把 label 存进数据库？

展示文案可能改动、翻译或按场景变化。数据库通常保存稳定的 backing value，读取后恢复枚举，再由行为方法或本地化层生成文案。

我现在判断这类设计时只问一句：这段代码是在约束“能做什么”，还是在约束“线上传什么”。前者属于接口，后者属于序列化协议。把两者分开，枚举既能保持领域表达力，也不会把一次普通重构变成数据兼容事故。