PHP 反射读取联合类型怎么做运行时校验：ReflectionType 与可空参数的判断顺序

线上表单校验器需要根据方法签名生成错误提示时，最容易踩的坑不是“拿不到类型”，而是把 ReflectionNamedType、ReflectionUnionType 和 null 当成一个字符串处理。这样一来，单类型参数能工作，联合类型一上线就会漏判或报错。

问题现场：getType() 返回的不是固定字符串

假设一个参数校验器要把方法签名展示给后台表单，它可能遇到下面三种声明：

调用 ReflectionParameter::getType() 后，第一种通常是 ReflectionNamedType，第二种是 ReflectionUnionType，第三种仍然是命名类型对象，只是 allowsNull() 返回 true。如果代码直接写成 $parameter->getType()->getName()，联合类型就会在运行时出错。

先用类型对象定位分支，再提取名称

比较稳的做法是先判断对象类型。联合类型不是一个需要猜字符串格式的特殊名字，而是一个可以继续遍历的类型集合。

function describeParameter(ReflectionParameter $parameter): array
{
    $type = $parameter->getType();

    if ($type === null) {
        return ['types' => [], 'allows_null' => true, 'required' => !$parameter->isOptional()];
    }

    if ($type instanceof ReflectionUnionType) {
        $types = array_map(
            static fn (ReflectionNamedType $named): string => $named->getName(),
            $type->getTypes()
        );
    } else {
        $types = [$type->getName()];
    }

    return [
        'types' => $types,
        'allows_null' => $type->allowsNull(),
        'required' => !$parameter->isOptional(),
    ];
}

这里的关键不是把代码写得更短，而是让返回值稳定：调用方永远拿到 types、allows_null 和 required 三个字段。后面无论是生成表单、记录接口文档，还是做输入校验，都不必再次判断反射对象。

可空参数要和“没有类型”分开处理

function three(?string $keyword) 有明确的 string 类型，只是允许 null。而没有类型的参数可能是 function four($value)，这时 getType() 返回 null，不能据此推断参数一定允许空值。

function isValueAllowed(mixed $value, array $description): bool
{
    if ($value === null) {
        return $description['allows_null'];
    }

    foreach ($description['types'] as $type) {
        if (matchesBuiltinType($value, $type) || $value instanceof $type) {
            return true;
        }
    }

    return false;
}

示例里的 matchesBuiltinType 应对 int、string、bool、float、array、object 等内置类型做显式映射；类名则交给 instanceof。不要把任意字符串直接拼成类判断，尤其要对 mixed、never 和 void 设定清晰的业务边界。

验证结果应该能解释“为什么不通过”

仅返回一个布尔值不利于排查。更实用的结果至少保留参数名、声明类型、收到的值类型和失败原因：

[
    'parameter' => 'value',
    'declared' => ['int', 'string'],
    'allows_null' => false,
    'received' => 'array',
    'valid' => false,
]

当联合类型含有类名时，展示名可以使用反射返回的完整名称；当类型是内置类型时，保留 PHP 的原名。日志里不要只写“类型错误”，否则下一次只能重新复现请求才能判断是联合分支漏了、空值规则错了，还是调用方传了数组。

常见误区与回归检查

• 误把 ReflectionUnionType 当成 ReflectionNamedType 调用 getName()。
• 看到 allowsNull() 为真就把“无类型参数”也当成可空。
• 只用 get_debug_type() 比较结果，遗漏了类继承关系和内置类型映射。
• 修改校验器后只测单类型，没有覆盖 int|string、?string、无类型和类联合类型。

回归时建议把每种声明都变成一个小样本，断言类型列表、空值策略和失败描述三个结果。这样 PHP 小版本变化或业务新增类型时，差异会直接落在测试输出里。

延伸问答

ReflectionType 可以直接转成字符串吗？

可以使用字符串化结果做展示，但业务判断仍应依据对象类型、getTypes() 和 allowsNull()，不要依赖字符串格式拆分。

联合类型中的 null 需要自己过滤吗？

如果只想展示实际类型，可以过滤名称为 null 的项；是否允许传入空值仍建议以 allowsNull() 为准。

没有类型声明的参数应该怎么校验？

先把它标记为“未声明”，再由业务规则决定是否接受；不要从反射结果自动推导成 mixed 或必然可空。

总结

PHP 反射的类型读取应遵循一个顺序：先拿到 ReflectionType，再区分命名类型和联合类型，最后结合 allowsNull() 与参数是否可选生成结构化描述。这个边界处理好后，运行时校验器才不会因一个新联合类型声明突然崩掉。