从PHPDoc迁移至Psalm时Pagerfanta模板返回值引发TooManyTemplateParams错误的问题求助

我来帮你梳理下问题所在，以及怎么修复这个错误。

问题根源 #

你的代码里的PHPDoc标注写法在Psalm中是不兼容的，主要有两个问题：

1. 语义矛盾：方法的返回类型已经明确声明为Pagerfanta，但你在PHPDoc里写了@return Pagerfanta|Message[]，这表示返回值可能是分页器实例，也可能是Message数组，和方法的实际返回类型冲突了。
2. 泛型标注错误：Pagerfanta是一个泛型类，需要明确指定它内部包含的元素类型。你原来的写法没有用Psalm认可的泛型标注方式，反而用了联合类型，导致Psalm误解你试图给Pagerfanta传递多个模板参数（而它本身只接受一个），所以触发了TooManyTemplateParams错误。

修复方案 #

把PHPDoc的返回标注改成泛型格式，明确指定Pagerfanta的元素类型是Message：

class Message {}
interface FooInterface {
    /** @return Pagerfanta<Message> */
    public function getMessages(): Pagerfanta;
}

为什么这样改？ #

• Pagerfanta的泛型设计是用来定义它所分页的元素类型，Pagerfanta<Message>表示这个分页器实例中包含的每个元素都是Message对象，完全符合方法返回分页器的语义。
• 这种写法既和方法的返回类型Pagerfanta保持一致，又正确遵循了Psalm对泛型类的标注规范，不会再触发参数数量不匹配的错误。

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