PHPDoc 中如何为泛型返回类型定义动态类名？

phpdoc 支持通过 `@template` 和 `class-string` 实现泛型返回类型推断，使 ide（如 phpstorm、vs code）能正确识别运行时传入的类名并提供精准类型提示与自动补全。

在 PHP 中，原生不支持函数级泛型（如 function create()），但借助现代 PHPDoc 标准（尤其是 Psalm 扩展语法 + PHPStan 兼容约定），可实现类型安全的工厂方法签名声明，从而让 IDE 理解 $obj = X::create('MyClass') 的返回值是 MyClass 实例，而非笼统的 object。

✅ 推荐写法（兼容 Psalm、PHPStan 与主流 IDE）

/**
 * 创建指定类的实例
 * @template T of object
 * @param class-string $class 类的完整限定名（如 'App\Models\User'）
 * @return T 实例化后的对象，类型精确到传入的类
 */
public function create(string $class): object
{
    return new $class();
}

? class-string 是 PHPStan/PSALM 定义的标准类型，表示“一个字符串字面量，其值是类 T 的类名”。配合 @template T of object，即可建立参数字符串 → 返回对象类型的双向绑定。

? 使用示例

$repo = $factory->create('App\Repositories\UserRepository');
// IDE 此时将识别 $repo 为
 UserRepository 类型，
// 支持 method() 补全、属性跳转、类型检查等完整智能提示。

⚠️ 注意事项

• IDE 支持现状：

  • ✅ PHPStorm 2025.3+ 已原生支持 @template + class-string 组合推断（需启用「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：
  这种写法不符合任何主流标准（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
兼容 PHPStan / Psalm	同上，二者均原生支持
最小侵入式升级	无需修改函数签名（仍可返回 object），仅增强注解
避免误用	禁用 @return object<...>、@return $class 等非标准写法

通过合理使用模板注解，你可以在不引入复杂依赖（如 PHP Generics RFC）的前提下，显著提升工厂类、容器、ORM 构建器等场景的开发体验与代码健壮性。