PHP中利用PHPDoc与Psalm精确标注类字符串数组

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

public function fromTopicAndData(string $topic, array $data) : Event
{
    // ... 逻辑 ...
    $eventClass = ($this->events)[$topic];
    return $eventClass::createFromData($data);
}

<?php

/**
 * 抽象事件基类
 */
abstract class Event
{
    /**
     * 从数据创建事件实例的静态工厂方法。
     *
     * @param array<string, mixed> $data 用于创建事件的数据
     * @return static 返回当前调用类的实例
     */
    public static function createFromData(array $data): static
    {
        // 示例实现，实际逻辑根据业务需求可能包含数据解析和属性赋值
        return new static();
    }
}

/**
 * 具体事件：文章创建事件
 */
class PostCreatedEvent extends Event {}

/**
 * 具体事件：运动执行事件
 */
class ExerciseExecutedEvent extends Event {}

/**
 * 事件工厂类，负责根据主题创建事件实例。
 */
class EventFactory
{
    /**
     * @var array<string, class-string<Event>> 存储事件主题到事件类字符串的映射。
     *                                          确保所有类字符串都继承自Event。
     */
    private array $events = [
        'post_created' => PostCreatedEvent::class,
        'exercise_executed' => ExerciseExecutedEvent::class,
    ];

    /**
     * 根据主题和数据创建事件实例。
     *
     * @param string $topic 事件主题
     * @param array<string, mixed> $data 事件所需数据
     * @return Event 返回一个Event或其子类的实例
     * @throws Exception 如果主题无效
     */
    public function fromTopicAndData(string $topic, array $data) : Event
    {
        if (! array_key_exists($topic, $this->events)) {
            throw new Exception('Invalid Topic: ' . $topic);
        }

        $eventClass = ($this->events)[$topic];
        // 借助PHPDoc标注，Psalm现在能够验证 $eventClass 是 Event 或其子类的类字符串，
        // 并且可以检查 createFromData 方法的存在和签名。
        return $eventClass::createFromData($data);
    }

    /**
     * 添加新的事件映射。
     *
     * @param string $topic 新事件的主题
     * @param class-string<Event> $eventClass 新事件的类字符串，必须是Event或其子类
     * @return void
     */
    public function addEvent(string $topic, string $eventClass): void
    {
        $this->events[$topic] = $eventClass; // Psalm OK
    }

    /**
     * 尝试添加一个不符合约束的类字符串（此方法仅用于演示Psalm的错误检测）。
     * 如果尝试将非Event子类的类字符串赋值给 $this->events，Psalm会报告类型错误。
     *
     * @param string $topic
     * @param class-string<stdClass> $invalidEventClass 故意使用错误的约束，用于演示
     * @return void
     */
    public function addInvalidEvent(string $topic, string $invalidEventClass): void
    {
        // $this->events[$topic] = $invalidEventClass; // 如果取消注释，Psalm会报告类型错误！
    }
}

// 示例使用
$factory = new EventFactory();
try {
    $postEvent = $factory->fromTopicAndData('post_created', ['id' => 1, 'title' => 'New Post']);
    echo "Created event: " . get_class($postEvent) . "\n"; // Output: Created event: PostCreatedEvent

    $exerciseEvent = $factory->fromTopicAndData('exercise_executed', ['user_id' => 10, 'duration' => 60]);
    echo "Created event: " . get_class($exerciseEvent) . "\n"; // Output: Created event: ExerciseExecutedEvent

    // 尝试添加一个不兼容的类。如果取消注释，Psalm会在此处报告错误。
    // $factory->addEvent('some_other_thing', stdClass::class);

    // 运行时错误示例（如果topic不存在）
    // $invalidEvent = $factory->fromTopicAndData('non_existent_topic', []); // Throws Exception
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}