php/app/utils/EnumUtil.php

<?php

namespace app\utils;

use ReflectionClass;

/**
 * 智能枚举验证器
 * 自动发现并验证请求参数中的枚举字段
 */
class EnumUtil
{
    /**
     * 自动验证请求参数中的枚举字段
     *
     * @param string|object $enumClassOrInstance 枚举类名或实例
     * @param array $requestData 请求数据
     * @return array 验证结果 ['valid' => bool, 'errors' => array]
     */
    public static function autoValidate($enumClassOrInstance, array $requestData): array
    {
        $errors = [];
        
        try {
            $reflection = new ReflectionClass($enumClassOrInstance);
            $constants = $reflection->getConstants();

            foreach ($constants as $constName => $enumValues) {
                if (!is_array($enumValues)) {
                    continue;
                }
                
                // 跳过MAP格式的枚举定义（包含code字段的）
                if (self::isMapFormat($enumValues)) {
                    continue;
                }

                // 将枚举常量名转换为可能的请求字段名
                $fieldName = self::constToFieldName($constName);

                // 检查请求数据中是否存在该字段
                if (array_key_exists($fieldName, $requestData)) {
                    $value = $requestData[$fieldName];
                    $result = self::validateEnumValue($value, $enumValues, $constName);
                    if (!$result['valid']) {
                        $errors[] = $result['error'];
                    }
                }
            }

        } catch (\ReflectionException $e) {
            return [
                'valid' => false,
                'errors' => ["枚举验证异常: " . $e->getMessage()]
            ];
        }

        if (!empty($errors)) {
            return [
                'valid' => false,
                'errors' => $errors
            ];
        }

        return [
            'valid' => true,
            'errors' => []
        ];
    }

    /**
     * 将枚举常量名转换为字段名
     *
     * @param string $constName 常量名称
     * @return string 字段名
     */
    private static function constToFieldName(string $constName): string
    {
        // 将下划线命名转换为蛇形命名（小写+下划线）
        return strtolower($constName);
    }

    /**
     * 验证单个枚举值
     *
     * @param mixed $value 要验证的值
     * @param array $enumValues 枚举值数组
     * @param string $constName 常量名称
     * @return array 验证结果 ['valid' => bool, 'error' => string|null]
     */
    private static function validateEnumValue($value, array $enumValues, string $constName): array
    {
        if (!is_array($enumValues) || empty($enumValues)) {
            return [
                'valid' => false,
                'error' => '枚举值配置错误'
            ];
        }

        // 提取所有有效值（简单格式的键）
        $validValues = array_keys($enumValues);

        // 处理字符串数字和整数的类型转换
        $normalizedValue = is_numeric($value) ? (int)$value : $value;
        
        if (!in_array($normalizedValue, $validValues, true)) {
            $fieldName = self::constToFieldName($constName);
            return [
                'valid' => false,
                'error' => "{$fieldName}参数错误，值：{$value}"
            ];
        }

        return [
            'valid' => true,
            'error' => null
        ];
    }

    /**
     * 获取枚举类的所有字段映射
     *
     * @param string|object $enumClassOrInstance 枚举类名或实例
     * @return array 字段映射 [字段名 => 枚举值数组]
     */
    public static function getFieldMappings($enumClassOrInstance): array
    {
        $mappings = [];
        
        try {
            $reflection = new ReflectionClass($enumClassOrInstance);
            $constants = $reflection->getConstants();

            foreach ($constants as $constName => $enumValues) {
                if (is_array($enumValues) && !self::isMapFormat($enumValues)) {
                    $fieldName = self::constToFieldName($constName);
                    $mappings[$fieldName] = $enumValues;
                }
            }

        } catch (\ReflectionException $e) {
            // 忽略异常，返回空数组
        }

        return $mappings;
    }

    /**
     * 检查枚举值数组是否为MAP格式（包含code字段）
     *
     * @param array $enumValues 枚举值数组
     * @return bool
     */
    private static function isMapFormat(array $enumValues): bool
    {
        // 如果是空数组，跳过
        if (empty($enumValues)) {
            return false;
        }
        
        // 检查第一个元素是否包含code字段
        $firstValue = reset($enumValues);
        return is_array($firstValue) && isset($firstValue['code']);
    }
}