如何为IteratorAggregate编写兼容Psalm与PhpStorm的类型提示

核心问题分析 #

Psalm对IteratorAggregate的泛型推导要求明确的类型约束，而PhpStorm需要清晰的返回类型注解来提供代码提示。此前的实现缺乏泛型层面的声明，导致两者无法同时兼容。

分步解决方案 #

1. 给基类添加泛型约束 #

让AbstractCollection实现带泛型的IteratorAggregate接口，用泛型占位符指定元素类型，为子类预留扩展空间：

abstract class AbstractCollection implements IteratorAggregate<mixed>
{
    protected array $items = [];

    /**
     * @return ArrayIterator<mixed>
     */
    public function getIterator(): Traversable
    {
        return new ArrayIterator($this->items);
    }

    // 其他通用集合方法（如count、clear等）
}

2. 子类明确具体泛型类型 #

子类继承时通过DocBlock注解（或PHP 8.0+原生泛型）指定元素类型，让Psalm和PhpStorm都能准确推导遍历元素：

方案A：PHP 7.x 兼容（DocBlock注解）

/**
 * @template T of object
 * @extends AbstractCollection<T>
 */
class Collection extends AbstractCollection
{
    public function add(T $item): void
    {
        $this->items[] = $item;
    }
}

方案B：PHP 8.0+ 原生泛型（更简洁）

abstract class AbstractCollection<T> implements IteratorAggregate<T>
{
    protected array $items = [];

    public function getIterator(): ArrayIterator<T>
    {
        return new ArrayIterator($this->items);
    }
}

class Collection<T extends object> extends AbstractCollection<T>
{
    public function add(T $item): void
    {
        $this->items[] = $item;
    }
}

3. 验证遍历类型提示 #

遍历集合时，无需额外注释，Psalm和PhpStorm会自动识别元素类型：

$collection = new Collection();
$collection->add(new stdClass());

foreach ($collection as $item) {
    // Psalm和PhpStorm均会识别$item为stdClass
    $item->foo = 'bar';
}

4. 修复Psalm报错 #

确保Psalm配置文件（psalm.xml）启用泛型支持（默认已开启，若报错可检查）：

<psalm>
    <strictnessLevel>1</strictnessLevel>
    <plugins>
        <pluginClass="Psalm\Plugin\UnusedCodePlugin\Plugin"/>
    </plugins>
</psalm>

若仍有报错，可给getIterator方法明确泛型返回类型（如上述代码中的ArrayIterator<T>）。

内容的提问来源于stack exchange，提问作者nickel715