Composer库不处理PHP枚举序列化，json_encode()默认将枚举转为空对象{}，需手动干预；最优解是通过__toString()或value属性显式转换，或封装trait统一处理，并用tryFrom()安全反序列化。
直接说结论：Composer 库本身不处理 PHP 枚举的序列化逻辑，json_encode() 默认把枚举对象转成空对象 {}，必须手动干预。所谓“优化封装”，本质是绕过 Composer 的自动序列化路径，改用可控的、带枚举感知能力的数据导出方式。
为什么 json_encode() 会把枚举变成 {}
PHP 原生 json_encode() 不识别枚举类型，只把它当普通对象处理；而枚举实例没有可序列化的 public 属性，也没有实现 JsonSerializable 接口（PHP 8.2+ 才默认支持），结果就是输出空对象。这不是 Composer 的 bug，而是底层序列化机制的限制。
- 即使你用 Composer 加载了含枚举的类，
json_encode($data)依然照常失效 -
serialize()能保留枚举实例，但那是 PHP 特有格式，不能用于 API 或前端交互 - Laravel、Symfony 等框架的响应序列化也受此影响，除非显式适配
用 __toString() 或 value 属性做轻量级兼容
最简单且兼容性最好的方案：让背书枚举（Backed Enum）自己决定怎么“说”出来。不依赖外部库，也不改框架行为。
- 对
enum Status: string，在枚举里加public function __toString(): string { return $this->value; } - 对
enum Code: int，同样实现__toString()返回(string)$this->value - 调用时直接
json_encode(['status' => Status::Active])→{"status":"active"} - 注意：
__toString()只在字符串上下文隐式触发，json_encode()不会自动调用它 —— 所以得先手动转：json_encode(['status' => (string)Status::Active])
封装通用的枚举序列化 trait
如果你的项目里枚举多、场景杂（API 返回、日志记录、缓存写入），重复写 (string)$e 或 $e->value 很容易漏。一个可复用的 trait 能统一行为：
立即学习“PHP免费学习笔记（深入）”；
trait SerializesEnums
{
public function toArray(): array
{
return array_map(fn($v) => $v instanceof \BackedEnum ? $v->value : $v, $this->jsonSerialize());
}
public function jsonSerialize(): mixed
{
return get_object_vars($this);
}
}
- 把这个 trait 加到 DTO、Resource 或 Model 类里
- 确保所有枚举字段都用
BackedEnum类型声明（否则instanceof判定失败） - 避免在
jsonSerialize()里直接递归处理嵌套结构——容易栈溢出，建议只处理一级属性
反序列化时别用 ::from()，优先 ::tryFrom()
接收 JSON 输入（如 API 请求体）时，从字符串还原枚举是最容易崩的环节。硬编码 Status::from($_POST['status']) 会直接抛 ValueError，导致 500 错误。
- 永远用
Status::tryFrom($raw)，它返回null而非异常 - 判空后，再决定是返回 400 错误、设默认值，还是丢进队列异步告警
- 不要在构造函数里无条件调用
::from()，那等于把校验责任甩给调用方 - 如果用 Laravel，可在 Form Request 的
rules()里配合自定义验证规则，例如'status' => ['required', new EnumRule(Status::class)]
真正麻烦的不是怎么写枚举，而是怎么让它们在数据流里“活下来”——从数据库读出来、经 HTTP 解析、被 JSON 打包、再传给前端或下游服务。每个环节都可能把枚举吃掉一层，最后只剩个空壳。越早明确哪一层负责序列化、哪一层负责反序列化，越不容易在半夜收到告警。
