PHP文档块中的@template注解代表什么含义？

核心作用 #

@template 是PHP生态中面向静态分析工具（如PHPStan、Psalm）的泛型声明注解，用于在PHP尚未支持原生泛型的版本中，实现泛型类型的约束与推导，提升开发阶段的类型校验能力和IDE自动补全体验，PHP运行时本身不会解析该注解。

结合示例代码逐行解释 #

你给出的Faker包中的注解代码如下：

/**
 * @template T of Extension\Extension
 *
 * @param class-string<T> $id
 *
 * @throws ContainerExceptionInterface
 * @throws Extension\ExtensionNotFound
 *
 * @return T
 */

各部分含义：

• @template T of Extension\Extension：声明名为T的泛型占位符，of Extension\Extension表示该泛型的取值范围只能是Extension\Extension类本身，或者继承/实现了该类的子类、接口实现类，避免泛型被传入不符合要求的类型。
• @param class-string<T> $id：约束入参$id必须是符合泛型T要求的类名字符串，也就是说你传入的类名必须属于Extension\Extension的派生类。
• @return T：声明方法返回值的类型和你传入的$id对应的类类型完全一致。

实际使用效果示例 #

假设你调用该方法时传入的$id为Faker\Extension\NumberExtension::class（该类实现了Extension\Extension接口），那么静态分析工具和IDE会自动推导该方法的返回值就是NumberExtension类型的实例，不需要你额外写类型转换注释，也能提前发现类型不匹配的错误。

这类泛型注解不会影响代码运行，仅作用于开发阶段的类型校验和提示。

内容的提问来源于stack exchange，提问作者Sherif Tarek