phpdoc 支持通过 `@template` 和 `class-string
在 PHP 中，原生不支持函数级泛型（如 function create<T>()），但借助现代 PHPDoc 标准（尤其是 Psalm 扩展语法 + PHPStan 兼容约定），可实现类型安全的工厂方法签名声明，从而让 IDE 理解 $obj = X::create('MyClass') 的返回值是 MyClass 实例，而非笼统的 object。
✅ 推荐写法（兼容 Psalm、PHPStan 与主流 IDE）
/**
* 创建指定类的实例
* @template T of object
* @param class-string<T> $class 类的完整限定名（如 'App\Models\User'）
* @return T 实例化后的对象，类型精确到传入的类
*/
public function create(string $class): object
{
return new $class();
}? class-string<T> 是 PHPStan/PSALM 定义的标准类型，表示“一个字符串字面量，其值是类 T 的类名”。配合 @template T of object，即可建立参数字符串 → 返回对象类型的双向绑定。
? 使用示例
$repo = $factory->create('App\Repositories\UserRepository');
// IDE 此时将识别 $repo 为 UserRepository 类型，
// 支持 method() 补全、属性跳转、类型检查等完整智能提示。⚠️ 注意事项
-
IDE 支持现状：
- ✅ PHPStorm 2023.3+ 已原生支持 @template + class-string<T> 组合推断（需启用「PHP Language Level ≥ 8.1」及「Enable PHPStan/PSALM integration」）。
- ✅ VS Code + intelephense（v1.9+）或 PHP Intelephense Pro 也已支持该语法；开源版需确保启用 intelephense.environment.phpVersion ≥ 8.1。
- ❌ 原生 PHPDoc（无静态分析工具）不解析 @template —— 它是静态分析增强注解，非运行时语义。
不要使用 @return object<$class>：
这种写法不符合任何主流标准（PHPDoc RFC、PSALM、PHPStan），IDE 将忽略或报错，且无法建立类型关联。-
类型安全性保障：
单靠 PHPDoc 无法阻止传入非法类名（如 'NonExistentClass'）。建议在运行时补充校验：if (!class_exists($class)) { throw new InvalidArgumentException("Class {$class} does not exist"); }
✅ 最佳实践总结
| 场景 | 推荐方案 |
|---|---|
| 需要 IDE 智能提示 | 使用 @template T of object + class-string<T> |
| 兼容 PHPStan / Psalm | 同上，二者均原生支持 |
| 最小侵入式升级 | 无需修改函数签名（仍可返回 object），仅增强注解 |
| 避免误用 | 禁用 @return object<...>、@return $class 等非标准写法 |
通过合理使用模板注解，你可以在不引入复杂依赖（如 PHP Generics RFC）的前提下，显著提升工厂类、容器、ORM 构建器等场景的开发体验与代码健壮性。
