phpdoc 支持 `@template` 与 `class-string
在 PHP 开发中，工厂方法（如 create(string $class): object）常需根据传入的类名字符串动态实例化对象。但原生 PHP 的 object 返回类型过于宽泛，IDE 无法识别具体类型，导致无法提供方法签名提示、属性跳转或自动补全等关键开发体验。
幸运的是，现代 PHPDoc 标准（结合 Psalm 类型注解）支持泛型模板（Generic Templates），可精确表达“返回类型由参数决定”的语义。以下是一个推荐的、兼容主流 IDE 的写法：
/**
* 创建指定类的实例
* @template T of object
* @psalm-param class-string<T> $class // Psalm 专用：声明 $class 是 T 的类名字符串
* @param class-string<T> $class // PHPStan/PHPStorm 可识别的等效注解
* @return T // 返回值即为 T 类型的实例
*/
public function create(string $class): object
{
if (!class_exists($class)) {
throw new InvalidArgumentException("Class {$class} does not exist");
}
return new $class();
}✅ 调用时效果示例：
$myVar = X::create('DateTimeImmutable');
// IDE 将正确识别 $myVar 为 DateTimeImmutable 类型
$myVar->format('Y-m-d'); // ✅ 自动补全可用
$myVar->nonExistentMethod(); // ❌ 类型检查报错（若启用严格模式）⚠️ 注意事项：
立即学习“PHP免费学习笔记（深入）”；
- @template T of object 声明泛型类型 T 必须是 object（即排除 string、int 等标量），确保类型安全；
- class-string
是 PHPStan / Psalm 支持的高级类型，表示“T 类的完全限定类名字符串”，比 string 更具语义； - PhpStorm 自 2023.3+ 版本起已原生支持 @template + class-string
推导 （需启用 “PHP Language Level ≥ 8.0” 并开启 “Enable PHPStan/PSALM support”）； - VS Code 需配合 PHP Intelephense（v1.9+）或 PHPStan extension 才能解析模板类型；纯内置语言服务暂不支持；
- 若需最大兼容性（如旧版 IDE 或无静态分析工具），可补充 @var 注释作为兜底：
/** @var DateTimeImmutable $myVar */ $myVar = X::create('DateTimeImmutable');
? 进阶建议：
对于更复杂的泛型工厂（如带构造参数），可扩展为：
/**
* @template T of object
* @psalm-param class-string<T> $class
* @psalm-param array<array-key, mixed> $args
* @param class-string<T> $class
* @param array $args
* @return T
*/
public function createWithArgs(string $class, array $args): object { ... }通过合理运用 @template 和 class-string
