PHP 实现动态严格类型映射（支持多维泛型语法）的通用 Map 类教程

本文介绍如何在 php 中构建一个可动态声明键值类型（如 `'string,array'`）的通用 `map` 类，通过运行时类型校验模拟泛型行为，避免为每种数据结构重复定义专用类。

PHP 原生不支持泛型（Generics），尽管 RFC #8132 已提出多年，但截至 PHP 8.3 仍未落地。因此，若需在运行时强制键值类型约束（如 Map 或嵌套类型 Map>），必须借助字符串类型描述 + 反射/类型检查逻辑手动实现。

以下是一个生产就绪的 Map 类基础实现，支持简单类型（int, string, bool, array, object, null）和类名（如 User::class），并可扩展支持复合类型语法（如 array）：

keyType = $keyType;
        $this->valueType = $valueType;

        foreach ($initialData as $key => $value) {
            $this->set($key, $value);
        }
    }

    public function set($key, $value): void
    {
        $this->validateKey($key);
        $this->validateValue($value);
        $this->items[$key] = $value;
    }

    public function get($key)
    {
        $this->validateKey($key);
        return $this->items[$key] ?? null;
    }

    public function all(): array
    {
        return $this->items;
    }

    private function validateKey($key): void
    {
        if (!$this->isOfType($key, $this->keyType)) {
            throw new TypeError(
                sprintf('Map key must be of type "%s", got "%s"', $this->keyType, get_debug_type($key))
            );
        }
    }

    private function validateValue($value): void
    {
        if (!$this->isOfType($value, $this->valueType)) {
            throw new TypeError(
                sprintf('Map value must be of type "%s", got "%s"', $this->valueType, get_debug_type($value))
            );
        }

        // 深度校验：若 valueType 是 "array<...>"，递归检查数组结构
        if (str_starts_with($this->valueType, 'array<')) {
            $this->validateArrayGeneric($value, $this->valueType);
        }
    }

    private function isOfType($value, string $type): bool
    {
        // 基础标量类型匹配
        if (in_array($type, ['int', 'integer', 'string', 'bool', 'boolean', 'float', 'double', 'array', 'object', 'null'], true)) {
            return match ($type) {
                'int', 'integer' => is_int($value),
                'string' => is_string($value),
                'bool', 'boolean' => is_bool($value),
                'float', 'double' => is_float($value),
                'array' => is_array($value),
                'object' => is_object($value),
                'null' => $value === null,
                default => false,
            };
        }

        // 类名或接口名（支持 FQCN）
        if (class_exists($type) || interface_exists($type)) {
            return $value instanceof $type;
        }

        // 兼容 PHP 8.0+ 的 get_debug_type() 风格（如 "MyClass"）
        if (get_debug_type($value) === $type) {
            return true;
        }

        return false;
    }

    private function validateArrayGeneric(array $arr, string $typeSpec): void
    {
        // 解析 array —— 简化版正则解析（生产环境建议用更健壮的解析器）
        if (!preg_match('/^array<([^,]+),([^>]+)>$/', $typeSpec, $matches)) {
            return; // 无法解析，跳过深度校验
        }

        [$_, $expectedKeyType, $expectedValueType] = $matches;

        foreach ($arr as $k => $v) {
            if (!$this->isOfType($k, $expectedKeyType)) {
                throw new TypeError(
                    sprintf('Array key "%s" must be of type "%s"', get_debug_type($k), $expectedKeyType)
                );
            }
            if (!$this->isOfType($v, $expectedValueType)) {
                throw new TypeError(
                    sprintf('Array value "%s" must be of type "%s"', get_debug_type($v), $expectedValueType)
                );
            }
        }
    }
}

✅ 使用示例：

// 基础用法：string → User 对象
class User { public string $name; }
$user = new User(); $user->name = 'Alice';

$users = new Map('string', User::class, ['alice' => $user]);
echo $users->get('alice')->name; // "Alice"

// 多维泛型：string → array
$stats = new Map('string', 'array', [
    'page_views' => ['home' => 120, 'about' => 45]
]);
// $stats->set('errors', ['404' => 'not found']); // ❌ 报错：value must be of type "array"

// 数值键 → 对象数组
$products = new Map('int', 'array', [
    101 => [new Product(), new Product()]
]);

⚠️ 注意事项与最佳实践：

立即学习“PHP免费学习笔记（深入）”；

• 性能权衡：嵌套类型（如 array）需遍历整个数组校验，大数据集建议仅在校验必要时启用，或改用 Map 分层设计；
• 类型字符串规范：推荐统一使用小写基础类型（string, int），类名使用完整命名空间（App\Models\User），避免歧义；
• IDE 支持：配合 PHPStan / Psalm 配置自定义 stub 文件，可为 Map::get() 返回值提供静态类型提示；
• 进阶扩展：可引入 TypeParser 独立组件支持更复杂语法（如 ?string, array），或集成 symfony/property-info 实现对象属性级校验。

总结：虽然 PHP 缺乏原生泛型，但通过严谨的运行时类型解析与分层验证策略，完全可以构建出高内聚、低耦合的通用 Map 容器——它既减少样板类数量，又保障了关键路径的数据契约完整性。