phpdoc 支持通过 `@template` 和 `class-string
在 PHP 中，原生不支持运行时泛型，但现代 IDE 和静态分析工具（如 PHPStan、Psalm）可通过增强的 PHPDoc 注解实现“伪泛型”类型推导。要让 X::create('MyClass') 的返回值被识别为 MyClass 实例而非笼统的 object，关键在于将类名参数（字符串字面量）与返回类型建立类型绑定。
✅ 正确写法：结合 @template 与 class-string
/**
* 创建指定类的实例
* @template T of object
* @param class-string<T> $class 类的完整限定名（如 'App\Models\User'）
* @return T 返回该类的一个实例
*/
public function create(string $class): object
{
return new $class();
}? 说明：@template T of object 声明一个受限模板类型 T，必须是 object 的子类型（即任意类）；class-string 是 PHPStan/PSALM 定义的特殊类型，表示“能实例化为 T 类型的类名字符串”，它建立了字符串参数与返回类型的双向约束；尽管方法签名中仍写 : object（PHP 8.0+ 也支持 : object，但无法表达具体类），PHPDoc 的 @return T 才是 IDE 类型推导的核心依据。
? IDE 支持现状
| 工具 | 是否支持 @template + class-string |
备注 |
|---|---|---|
| PHPStorm 2023.3+ | ✅ 基本支持（需启用 PHPStan 或内置类型推导） | 在 Settings → PHP → Language Level ≥ 8.0 且开启 “Enable advanced type inference” 后效果更佳 |
| VS Code + intelephense | ⚠️ 部分支持（v1.9+ 对 class-string |
推荐搭配 PHPStan extension 获取完整泛型支持 |
| PHPStan / Psalm | ✅ 全面支持（推荐作为 CI 类型检查补充） | 在 phpstan.neon 中启用 phpstan-phpdoc-parser 即可解析 |
? 实际使用示例
class User { public function getName(): string { return 'Alice'; } }
class Post { public function getTitle(): string { return 'Hello'; } }
// 调用后，$user 和 $post 将获得完整类型提示
$user = X::create('User'); // IDE 识别为 User 类型 → 可点出 getName()
$post = X::create('Post'); // IDE 识别为 Post 类型 → 可点出 getTitle()⚠️ 注意事项
- ❌ 不要使用 @return object —— 这是无效语法，PHPDoc 规范和主流工具均不识别；
- ✅ 必须同时标注 @template、@param class-string
和 @return T，三者缺一不可； - ? 若项目未使用 Psalm/PHPStan，建议至少引入 phpstan/phpstan（dev 依赖）并配置基础规则，以激活 IDE 的高级类型推导能力；
- ? 对于 Laravel 等框架的工厂方法，可进一步封装为泛型静态代理，例如：
/** * @template T of object * @param class-string<T> $class * @return T */ public static function make(string $class): object { /* ... */ }
通过规范使用 PHPDoc 模板语法，你无需等待 PHP 原生泛型（PHP 9+ 计划中），即可在当前生态中获得接近强类型语言的开发体验。
