本文介绍如何通过 phpdoc 的 `@template` 和 `class-string
在 PHP 中，当实现工厂模式或动态实例化类（如 create('MyClass')）时，传统 @return object 或 @return mixed 注解无法向 IDE 传达具体的返回类型，导致无法获得准确的代码提示和类型检查。幸运的是，借助现代 PHPDoc 扩展规范（尤其是 Psalm 风格的泛型注解），我们可以实现类型安全的泛型返回声明。
✅ 推荐写法：使用 @template + class-string
/** * 创建指定类的实例 * @template T of object * @psalm-param class-string$class * @param class-string $class 类的完全限定名称（如 'App\Models\User'） * @return T 实例化后的具体对象（如 User） */ public function create(string $class): object { if (!class_exists($class)) { throw new InvalidArgumentException("Class {$class} does not exist."); } return new $class(); }
? 关键点说明：@template T of object：声明一个泛型类型 T，约束其必须是 object（即类实例）；class-string：表示 $class 是一个可实例化的类名字符串，且该类的实例类型即为 T；@return T：明确告知 IDE：返回值类型与传入的类名字符串所指向的类一致。
? 实际效果示例
调用时：
$user = $factory->create('App\Models\User');
// IDE 现在能正确识别 $user 是 App\Models\User 类型
$user->getName(); // ✅ 自动补全 & 类型检查生效
$user->nonExistentMethod(); // ❌ PHPStan/IDE 显示错误⚠️ 注意事项与兼容性说明
-
PhpStorm：自 2022.3 版本起已支持 @template 和 class-string
（需启用「PHP Language Level ≥ 8.0」并开启「Enable advanced PHP type inference」）。但对 @psalm-param 的兼容性有限，建议统一使用标准 PHPDoc 形式（省略 @psalm- 前缀），或配合 PHPStan / Psalm 进行静态分析。 -
VS Code + Intelephense：v1.9+ 支持 @template 和 class-string
，推荐启用 "intelephense.environment.phpVersion": "8.1" 以获得最佳泛型推断。 - 运行时无影响：所有注解仅用于静态分析和 IDE 提示，不改变实际执行逻辑。
- 安全增强建议：务必在方法内校验 class_exists($class) 和 is_subclass_of($class, 'SomeBase')（如需类型约束），避免运行时错误。
✅ 最佳实践总结
| 场景 | 推荐方式 |
|---|---|
| 简单工厂（返回任意类） | @template T of object + class-string |
| 限定基类（如只允许 Model 子类） | @template T of \App\Models\Model |
| 多参数泛型（如 createWithConfig(string $class, array $cfg)） | 可扩展为 @template T, @param class-string |
通过合理使用 PHPDoc 泛型注解，你不仅能显著提升开发体验（精准补全、零配置类型跳转），还能让团队代码更健壮、可维护性更强——让“魔法字符串”回归类型安全的轨道。
