PHP 8 Attributes 简介
attributes（属性）是 php 8 引入的一项强大特性，它允许开发者以声明式的方式向类、方法、属性、函数参数等代码元素添加结构化的元数据。这类似于其他语言中的注解（annotations），其核心目的是为代码提供额外的信息，而这些信息可以在运行时通过程序进行读取和处理。
定义自定义 Attribute
要创建一个自定义的 Attribute，需要定义一个类，并使用内置的 #[Attribute] Attribute 标记它。#[Attribute] 本身也可以接受参数，例如 Attribute::TARGET_CLASS、Attribute::TARGET_METHOD 等，用于限制该自定义 Attribute 可以应用的目标类型。
以下是一个简单的自定义 Attribute 定义示例：
<?php
use Attribute;
#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD)]
class MyAttribute
{
private string $message;
public function __construct(string $message)
{
$this->message = $message;
// 注意：这里的 echo 不会在声明时自动执行
// echo "Attribute constructor called with: " . $message . PHP_EOL;
}
public function getMessage(): string
{
return $this->message;
}
}
?>在这个例子中，MyAttribute 类被标记为 #[Attribute]，这意味着它可以作为其他代码元素的 Attribute 使用。构造函数接受一个 $message 参数，并将其存储起来。
应用 Attribute
一旦定义了 Attribute，就可以将其应用到相应的代码元素上。Attribute 的语法是 #[AttributeName(参数)]。
立即学习“PHP免费学习笔记（深入）”；
<?php
// 假设 MyAttribute 已定义在同一文件或已通过命名空间引入
#[MyAttribute('Hello from SomeClass')]
class SomeClass
{
#[MyAttribute('Hello from someMethod')]
public function someMethod(): void
{
// ...
}
// ...
}
?>在这里，MyAttribute 被应用到了 SomeClass 类和 someMethod 方法上，并传入了不同的消息字符串。
理解 Attribute 构造函数的执行时机
初学者常常会有一个疑问：为什么在 Attribute 的构造函数中放置 echo 语句，但在代码运行时却看不到任何输出？例如，在 MyAttribute 的构造函数中加入 echo $message;，但当 SomeClass 被声明时，并不会立即打印 "Hello"。
这是因为 Attributes 本质上是被动元数据。它们在代码中声明时，PHP 引擎仅仅是解析并存储了这些元数据，而不会立即实例化或执行它们的构造函数。Attribute 的构造函数只有在通过反射（Reflection）机制显式地访问并实例化该 Attribute 时才会被调用。Attributes 并非在声明时就执行的逻辑，而是等待程序在运行时主动查询并处理的额外信息。
通过反射访问和实例化 Attributes
要获取和利用 Attributes 承载的信息，必须使用 PHP 的反射 API。反射允许程序在运行时检查自身结构，包括类、方法、属性等，并可以获取附加在这些元素上的 Attributes。
以下是访问和实例化 MyAttribute 的完整示例：
<?php
use Attribute;
use ReflectionClass;
use ReflectionMethod;
// 1. 定义自定义 Attribute
#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD)]
class MyAttribute
{
private string $message;
public function __construct(string $message)
{
$this->message = $message;
echo "MyAttribute 构造函数被调用，消息: " . $message . PHP_EOL;
}
public function getMessage(): string
{
return $this->message;
}
}
// 2. 应用 Attribute
#[MyAttribute('Hello from SomeClass')]
class SomeClass
{
#[MyAttribute('Hello from someMethod')]
public function someMethod(): void
{
echo "someMethod 被执行。" . PHP_EOL;
}
}
// 3. 通过反射访问 Attributes
// 访问类的 Attributes
$reflectionClass = new ReflectionClass(SomeClass::class);
echo "--- 访问类 Attributes ---" . PHP_EOL;
$classAttributes = $reflectionClass->getAttributes();
if (!empty($classAttributes)) {
foreach ($classAttributes as $attribute) {
// $attribute 是 ReflectionAttribute 实例
echo "发现类 Attribute: " . $attribute->getName() . PHP_EOL;
// 实例化 Attribute，此时 MyAttribute 的构造函数才会被调用
$myAttributeInstance = $attribute->newInstance();
echo "实例化后的消息: " . $myAttributeInstance->getMessage() . PHP_EOL;
}
} else {
echo "未找到类的 Attributes。" . PHP_EOL;
}
echo PHP_EOL;
// 访问方法的 Attributes
$reflectionMethod = new ReflectionMethod(SomeClass::class, 'someMethod');
echo "--- 访问方法 Attributes ---" . PHP_EOL;
$methodAttributes = $reflectionMethod->getAttributes();
if (!empty($methodAttributes)) {
foreach ($methodAttributes as $attribute) {
echo "发现方法 Attribute: " . $attribute->getName() . PHP_EOL;
$myAttributeInstance = $attribute->newInstance();
echo "实例化后的消息: " . $myAttributeInstance->getMessage() . PHP_EOL;
}
} else {
echo "未找到方法的 Attributes。" . PHP_EOL;
}
?>代码解析：
- new ReflectionClass(SomeClass::class): 创建 ReflectionClass 实例，用于反射 SomeClass。
- $reflectionClass->getAttributes(): 获取附加到 SomeClass 上的所有 Attributes。它返回一个 ReflectionAttribute 对象的数组。
- $attribute->getName(): 获取 ReflectionAttribute 实例所代表的 Attribute 类的完全限定名称（如 MyAttribute）。
- $attribute->newInstance(): 这是关键一步。它会根据 ReflectionAttribute 的信息，使用其构造函数参数来创建一个 MyAttribute 的新实例。此时，MyAttribute 的构造函数才会被实际调用，并执行其中的逻辑（例如 echo 语句）。
- $myAttributeInstance->getMessage(): 访问实例化后的 MyAttribute 对象的方法，获取其内部存储的数据。
除了 ReflectionClass，PHP 还提供了其他反射类来访问不同代码元素的 Attributes，例如：
- ReflectionMethod: 用于反射类方法。
- ReflectionProperty: 用于反射类属性。
- ReflectionFunction: 用于反射全局函数。
- ReflectionParameter: 用于反射函数或方法的参数。
- ReflectionClassConstant: 用于反射类常量。
注意事项与总结
- Attributes 是元数据，而非直接执行的代码。 它们在声明时不会自动执行构造函数，只有通过反射显式实例化时才会执行。
- 反射是访问 Attributes 的唯一途径。 任何想要在运行时读取或处理 Attributes 的逻辑，都必须依赖反射 API。
- #[Attribute] 标记是必需的。 只有被 #[Attribute] 标记的类才能作为 Attribute 使用。
- Attribute 类的构造函数参数 可以是常量表达式，也可以是运行时可计算的值，但它们必须在编译时可确定。
- Attributes 的应用场景广泛，包括但不限于路由定义、ORM 映射、权限控制、序列化/反序列化配置、测试框架等。它们提供了一种比 PHPDoc 更结构化、更类型安全且更易于解析的方式来添加元数据。
通过深入理解 Attributes 的工作原理和反射机制，开发者可以更有效地利用 PHP 8 的这一强大特性，构建更加灵活和可扩展的应用程序。
