如何自动为 PHP 原生枚举实现 JMS Serializer 序列化支持-php教程-PHP中文网

如何自动为 PHP 原生枚举实现 JMS Serializer 序列化支持

本文介绍一种无需为每个 php 枚举手动编写专用序列化器类的方案，通过反射动态识别目标属性类型，在 jms serializer 中统一处理 backed enum 的序列化与反序列化，显著减少模板代码。

本文介绍一种无需为每个 php 枚举手动编写专用序列化器类的方案，通过反射动态识别目标属性类型，在 jms serializer 中统一处理 backed enum 的序列化与反序列化，显著减少模板代码。

在使用 JMS Serializer 处理 PHP 8.1+ 原生 backed enums（如 enum MyEnum: string）时，常见做法是为每个枚举实现一个继承自 SubscribingHandlerInterface 的专用序列化器类——但这导致大量重复样板代码，违背开闭原则，也增加了维护成本。

理想方案是：注册一个通用处理器，能自动识别当前反序列化/序列化的字段类型是否为 backed enum，并交由其原生 ::from() 和 ->value 机制处理。虽然 JMS Serializer 官方不直接支持“泛型枚举处理器”，但可通过巧妙利用上下文与反射实现近似效果。

✅ 推荐方案：单处理器 + 属性类型反射（支持反序列化）

以下是一个可复用的通用反序列化处理器，适用于所有 string|int backed enums：

<?php namespace AppSerializer;

use JMSSerializerGraphNavigator;
use JMSSerializerHandlerSubscribingHandlerInterface;
use JMSSerializerJsonDeserializationVisitor;
use JMSSerializerContext;
use ReflectionProperty;

class GenericEnumDeserializationHandler implements SubscribingHandlerInterface
{
    public static function getSubscribingMethods(): array
    {
        return [
            [
                'direction' => GraphNavigator::DIRECTION_DESERIALIZATION,
                'format' => 'json',
                'type' => 'enum', // 占位符类型（实际由 isApplicable 拦截）
                'method' => 'deserializeEnum',
            ],
        ];
    }

    public function deserializeEnum(
        JsonDeserializationVisitor $visitor,
        $data,
        array $type,
        Context $context
    ) {
        // 获取当前正在反序列化的对象（如 DTO 或实体）
        $currentObject = $visitor->getCurrentObject();
        if (!$currentObject) {
            throw new RuntimeException('Cannot deserialize enum: no current object context.');
        }

        // 解析当前路径（如 ["user", "status"]），取最后一个字段名
        $path = $context->getCurrentPath();
        if (empty($path)) {
            throw new RuntimeException('Cannot determine target property name from serialization context.');
        }
        $propertyName = $path[array_key_last($path)];

        // 反射获取该属性的声明类型
        $refClass = new ReflectionClass($currentObject::class);
        if (!$refClass->hasProperty($propertyName)) {
            throw new InvalidArgumentException("Property {$propertyName} not found in {$currentObject::class}");
        }

        $refProp = $refClass->getProperty($propertyName);
        $refProp->setAccessible(true);

        $propType = $refProp->getType();
        if (!$propType || !$propType->getName()) {
            throw new RuntimeException("Property {$propertyName} has no type declaration in {$currentObject::class}");
        }

        $enumClass = $propType->getName();
        $isNullable = $propType->allowsNull();

        // 兼容 null 值（仅当属性类型允许 null）
        if ($data === null && $isNullable) {
            return null;
        }

        // 验证目标类是否为有效 backed enum
        if (!enum_exists($enumClass) || !is_subclass_of($enumClass, UnitEnum::class)) {
            throw new UnexpectedValueException("{$enumClass} is not a valid backed enum");
        }

        // 使用原生 ::from() 安全反序列化（自动抛出 ValueError 若值无效）
        try {
            return $enumClass::from($data);
        } catch (ValueError $e) {
            throw new UnexpectedValueException(
                "Invalid value '{$data}' for enum {$enumClass}: {$e->getMessage()}"
            );
        }
    }
}

✅ 优势：只需注册一次该处理器，所有带类型提示的 enum 属性（如 public MyEnum $status;）将自动被处理，无需为 MyEnum、StatusEnum、RoleEnum 等分别写 MyEnumSerializer。

⚠️ 注意事项与限制

仅支持反序列化（JSON → PHP）：上述方案依赖 $visitor->getCurrentObject() 和 $context->getCurrentPath()，而序列化方向（PHP → JSON）中 getCurrentObject() 通常为 null，因此不适用于通用序列化逻辑。若需双向支持，仍建议保留 AbstractEnumSerializer + 自动服务注册（见下文补充方案）。
要求属性有完整类型声明：必须使用 MyEnum $field;，而非 ?MyEnum $field;（虽支持 nullable，但需显式声明 ?MyEnum）或无类型提示。
不支持嵌套数组/集合中的 enum：如 public array $statuses; 或 public Collection $items; 中的 enum 元素无法通过此方式识别——此时仍需显式配置或使用 @Type 注解。
性能影响极小：反射仅在反序列化失败时触发（即按需），且现代 PHP 对反射缓存友好。

? 补充方案：全自动双向支持（推荐生产环境）

若需序列化 + 反序列化全自动化，可结合 Symfony 容器（或其他 DI 容器）实现“枚举自动发现与注册”：

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

扫描 AppEnum 命名空间下所有 enum 类；
为每个枚举动态生成匿名 SubscribingHandlerInterface 实例（或使用 class_alias + spl_autoload_register 延迟加载）；
在容器中批量注册这些处理器。

示例（Symfony + PHP 8.2+）：

// In your bundle's extension or compiler pass
$enums = $this->findBackedEnumsInNamespace('App\Enum\');
foreach ($enums as $enumClass) {
    $handler = new class($enumClass) implements SubscribingHandlerInterface {
        private string $enumClass;

        public function __construct(string $enumClass) {
            $this->enumClass = $enumClass;
        }

        public static function getSubscribingMethods(): array {
            return [
                [
                    'direction' => GraphNavigator::DIRECTION_DESERIALIZATION,
                    'format' => 'json',
                    'type' => self::$enumClass,
                    'method' => 'deserialize',
                ],
                [
                    'direction' => GraphNavigator::DIRECTION_SERIALIZATION,
                    'format' => 'json',
                    'type' => self::$enumClass,
                    'method' => 'serialize',
                ],
            ];
        }

        public function deserialize(JsonDeserializationVisitor $v, $data, array $t) {
            return $this->enumClass::tryFrom($data) ?? throw new UnexpectedValueException("Invalid value for {$this->enumClass}");
        }

        public function serialize($v, $enum, array $t, SerializationContext $c): mixed {
            return $enum->value;
        }
    };
    $container->set($enumClass . 'Serializer', $handler);
}

该方式真正实现“零手工序列化器”，新增枚举后仅需清缓存即可生效。