@template 注解用于在 PHP Doc Blocks 中模拟泛型，允许开发者在文档中描述参数或返回值的类型，即使这些类型在类实例化或方法调用之前是未知的。它主要用于提高代码的可读性和静态分析工具的准确性，虽然PHP本身并不直接支持泛型。
在 PHP 中，虽然语言本身并不直接支持泛型，但我们可以使用 PHPDoc 注解来模拟泛型的行为，从而提供更强的类型提示和代码分析能力。@template 注解就是其中的关键。
@template 的作用
@template 注解允许你在文档块中定义一个类型参数，这个类型参数可以在后续的参数类型、返回值类型等地方使用。它本质上是一种占位符，代表着一个具体的类型，这个类型在运行时才能确定。
立即学习“PHP免费学习笔记（深入）”；
语法结构
@template T of SomeClass
- T: 类型参数的名称，可以自定义，通常使用大写字母。
- of SomeClass (可选): 类型约束，指定 T 必须是 SomeClass 或其子类。
使用示例
以下是一个示例，展示了如何在 PHPDoc 中使用 @template 注解：
/** * @template T of Extension\Extension * * @param class-string$id * * @throws ContainerExceptionInterface * @throws Extension\ExtensionNotFound * * @return T */ public function ext(string $id) { // ... 实现 ... }
在这个例子中：
- @template T of Extension\Extension 定义了一个类型参数 T，并约束它必须是 Extension\Extension 类或其子类。
- @param class-string
$id 声明参数 $id 是一个类名字符串，并且这个类名必须是 T 所代表的类型。 class-string 是一个特殊的类型提示，表示一个字符串，其值为类名，并且该类必须是 T 类型的。 - @return T 声明返回值类型是 T，即返回的将是 Extension\Extension 或其子类的实例。
实际应用
假设我们有一个名为 MyExtension 的类，它继承自 Extension\Extension：
namespace MyNamespace;
use Extension\Extension;
class MyExtension extends Extension
{
// ...
}那么，我们可以这样使用 ext 方法：
$extension = $faker->ext(MyNamespace\MyExtension::class); // $extension 的类型将被静态分析工具推断为 MyNamespace\MyExtension
注意事项
- @template 注解本身不会影响 PHP 的运行时行为。它主要用于静态分析工具（如 PHPStan、Psalm）进行类型检查和代码提示。
- 类型约束 of SomeClass 是可选的。如果没有指定类型约束，则 T 可以代表任何类型。
- 可以定义多个 @template 注解，例如 @template K 和 @template V，用于表示键和值的类型。
总结
@template 注解是 PHP Doc Blocks 中一个强大的工具，它允许开发者在缺乏原生泛型支持的情况下，模拟泛型的行为，从而提高代码的可读性、可维护性和静态分析的准确性。 通过合理使用 @template 注解，可以编写出更健壮、更易于理解的 PHP 代码。 虽然它不能完全替代真正的泛型，但在现阶段，它是一个非常有用的替代方案。
