本文深入探讨了如何在PHP中使用PHPDoc和`class-string`类型标注，以正确地为存储类名字符串的数组进行类型提示。通过一个事件工厂的实际案例，我们展示了如何解决Psalm等静态分析工具在处理此类结构时可能出现的类型不明确问题，确保代码的类型安全性和可维护性，同时提升静态分析的准确性。

在现代PHP开发中，静态分析工具如Psalm已成为提升代码质量和减少潜在错误的关键。然而，当处理一些高级模式，例如工厂模式中动态加载类时，类型标注可能会变得复杂。一个常见场景是，我们有一个数组，其值是表示类名的字符串，并且这些类名都继承自一个共同的父类或实现了一个共同的接口。

场景描述：事件工厂中的类名数组

考虑以下事件工厂的实现。这个工厂根据传入的“主题”字符串，动态地实例化对应的事件类。

 PostCreatedEvent::class,
        'exercise_executed' => ExerciseExecutedEvent::class,
    ];

    public function fromTopicAndData(string $topic, array $data): Event
    {
        if (!array_key_exists($topic, $this->events)) {
            throw new \Exception('Invalid Topic');
        }

        $eventClassName = ($this->events)[$topic]; // $eventClassName 是一个字符串

        // Psalm 在这里可能会报告错误，因为它不知道 $eventClassName 到底是什么类的字符串，
        // 也不知道它是否一定具有 createFromData 静态方法。
        return $eventClassName::createFromData($data);
    }
}

?>

在这个EventFactory中，$events数组的键是主题字符串，值是对应的事件类名（如PostCreatedEvent::class）。所有这些事件类都继承自抽象的Event类，并且我们期望它们都实现了一个静态方法createFromData()。

问题在于，如果没有适当的类型标注，Psalm等静态分析工具在分析$eventClassName::createFromData($data)这一行时，无法确定$eventClassName这个字符串到底代表了哪个类，更无法保证它一定包含createFromData这个静态方法。这会导致Psalm发出警告或错误，降低代码的类型安全。

解决方案：使用 class-string 进行类型标注

为了解决这个问题，我们可以利用PHPDoc中的class-string类型。class-string表示一个字符串，该字符串的值是一个类的完全限定名，并且这个类必须是T类型本身或其子类/实现。

将此类型应用于$events数组，可以明确告知Psalm数组中存储的类名字符串的类型约束。

> */
    private array $events = [
        'post_created' => PostCreatedEvent::class,
        'exercise_executed' => ExerciseExecutedEvent::class,
    ];

    public function fromTopicAndData(string $topic, array $data): Event
    {
        if (!array_key_exists($topic, $this->events)) {
            throw new \Exception('Invalid Topic');
        }

        // 经过 PHPDoc 标注后，Psalm 现在知道 $eventClassName 是一个 Event 或其子类的类名字符串
        $eventClassName = ($this->events)[$topic];

        // Psalm 现在可以正确地验证这个静态方法调用
        return $eventClassName::createFromData($data);
    }
}

?>

标注解析：

• @var array>：
  • array：表示这是一个数组。
  • ：表示数组的键是字符串类型。
  • class-string：表示数组的值是一个字符串，但这个字符串必须代表一个类名，且该类必须是Event类或其任何子类。

通过这样的标注，Psalm就能理解：

1. $this->events数组中的每个值都是一个有效的类名字符串。
2. 更重要的是，这些类名字符串所代表的类，都保证是Event类或其子类。
3. 由于我们假设Event抽象类（或通过接口）声明了createFromData()静态方法，Psalm就能确信在$eventClassName::createFromData($data)这一行，被调用的静态方法是存在的且类型兼容的。

注意事项与最佳实践

1. 父类/接口声明方法：确保在class-string中的T类型（本例中是Event）中，声明了所有预期通过类名字符串调用的静态方法。如果Event类没有声明createFromData()，即使子类实现了，Psalm仍然可能发出警告，因为它只知道$eventClassName是一个Event或其子类的类名，而Event本身不保证有此方法。通常，抽象类或接口是声明这些共享方法的理想场所。

   abstract class Event
   {
       // 明确声明静态方法，即使是抽象的，也告知了Psalm其存在
       abstract public static function createFromData(array $data): self;
   }

2. 类型安全性：class-string提供了强大的类型安全性，它不仅验证了值是类名字符串，还进一步约束了这些类名的继承关系。这在处理插件系统、事件调度器、工厂模式等需要动态加载和实例化类的场景中尤为有用。

3. Psalm配置：确保你的Psalm配置（psalm.xml）已正确设置，以便它能够分析你的代码并识别这些PHPDoc标注。

总结

通过在PHPDoc中使用@var array>这样的类型标注，我们能够精确地描述PHP中存储类名字符串的数组的类型结构。这不仅帮助静态分析工具（如Psalm）更好地理解代码意图，消除误报，而且极大地提升了代码的类型安全性和可维护性。在构建复杂、动态的PHP应用时，掌握此类高级类型标注技巧至关重要。