PHP中如何通过PHPDoc让IDE识别抽象Builder类get方法的子类模型返回类型

你遇到的这个问题，本质是PHP静态类型推断里的「协变返回类型」场景，想要让IDE像识别Laravel Eloquent那样，自动感知子类构建器返回的是具体的子类模型而非抽象父类。这里有两种靠谱的解决方案：

方案一：使用PHPDoc泛型模板（推荐，兼容旧PHP版本） #

这是和Laravel Eloquent思路一致的写法，通过泛型模板在抽象类中声明类型占位符，子类继承时指定具体的模型类型，就能让IDE正确推断返回值类型。

首先修改抽象类的PHPDoc注释：

/**
 * @template T of Foo
 */
abstract class Foo { }

/**
 * @template T of Foo
 * @property T $model
 */
abstract class FooBuilder {
    protected Foo $model;

    /**
     * Return the class instance
     *
     * @return T
     */
    public function get() {
        return $this->model;
    }
}

然后子类继承时，通过@extends指定具体的泛型类型：

class Bar extends Foo { }

/**
 * @extends FooBuilder<Bar>
 */
class BarBuilder extends FooBuilder {
    public function __construct() {
        $this->model = new Bar();
    }
}

$barBuilder = new BarBuilder();
$bar = $barBuilder->get(); // 现在IDE会准确识别$bar的类型是Bar

解释一下：

• @template T of Foo：在抽象类中声明一个类型占位符T，它必须是Foo的子类
• @property T $model：告诉IDE，$model的类型是占位符T对应的具体类型
• 子类的@extends FooBuilder<Bar>：把占位符T替换成具体的Bar类，这样get()方法的返回类型就会被IDE推断为Bar

方案二：使用PHP 8.0+的协变返回类型 #

如果你的项目已经升级到PHP 8.0及以上，可以直接利用PHP原生的协变返回类型特性，在子类中重写get()方法并指定具体的返回类型：

abstract class Foo { }

abstract class FooBuilder {
    protected Foo $model;

    abstract public function get(): Foo;
}

class Bar extends Foo { }

class BarBuilder extends FooBuilder {
    protected Bar $model;

    public function __construct() {
        $this->model = new Bar();
    }

    // 协变返回类型：返回Bar（Foo的子类），符合PHP的类型规则
    public function get(): Bar {
        return $this->model;
    }
}

这种方式更偏向原生PHP语法，不需要依赖IDE对PHPDoc泛型的支持，但需要修改子类的代码结构，重写get()方法。

另外补充一点：部分IDE（比如PHPStorm）也支持@return $this->model这种简化写法，但泛型模板的方式更规范，跨IDE兼容性更好，也是Laravel等框架常用的做法。

内容的提问来源于stack exchange，提问作者André Walker