PHP 8引入的Attributes提供了一种声明式元数据机制，用于为类、方法、属性等添加结构化信息。与传统注解不同，Attributes并非自动执行，其构造函数仅在通过PHP反射API显式访问和实例化时才会被调用。本教程将详细介绍如何定义自定义Attributes，并利用Reflection API获取并实例化它们，从而实现灵活的元数据处理。
1. PHP 8 Attributes 简介
在php 8之前，开发者通常使用phpdoc块中的注解（例如@orm/column）来为代码添加元数据。然而，这些注解只是字符串，需要通过外部解析器（如doctrine annotations）进行处理，缺乏原生的语言支持和类型安全性。
PHP 8 Attributes（属性）正是为了解决这一问题而生。它提供了一种将结构化、机器可读的元数据直接嵌入到代码中的方式。Attributes本质上是特殊的PHP类，它们被标记在其他类、方法、属性、函数或参数的上方，用作声明性的标记或配置。
核心优势：
- 原生语言支持： Attributes是PHP语言的一部分，无需额外的库即可解析。
- 类型安全： Attributes的构造函数可以声明类型提示，提供编译时检查。
- 可组合性： 多个Attributes可以应用于同一个目标。
- 性能： 原生解析通常比用户空间的字符串解析更高效。
2. 定义自定义 Attribute
要创建一个自定义Attribute，你需要定义一个普通的PHP类，并使用内置的#[Attribute] Attribute来标记它。这个内置Attribute告诉PHP引擎该类可以用作一个Attribute。
示例：定义一个简单的 MyAttribute
立即学习“PHP免费学习笔记（深入）”；
<?php
use Attribute;
// 必须使用内置的 #[Attribute] 标记，以声明该类为一个Attribute
// Attribute::TARGET_CLASS 定义了该Attribute只能应用于类
// Attribute::IS_REPEATABLE 允许同一个Attribute在同一目标上重复使用
#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD | Attribute::IS_REPEATABLE)]
class MyAttribute
{
private string $message;
private ?string $tag;
/**
* Attribute 的构造函数用于接收和存储元数据。
*
* @param string $message 要存储的消息
* @param string|null $tag 可选的标签
*/
public function __construct(string $message, ?string $tag = null)
{
$this->message = $message;
$this->tag = $tag;
// 注意：Attributes的构造函数通常用于存储数据，
// 避免在此处执行有副作用的操作（如直接echo），
// 除非是调试或特定框架设计。
// 为了演示构造函数被调用，我们暂时保留echo。
echo "[DEBUG] MyAttribute 构造函数被调用，消息: " . $this->message . PHP_EOL;
}
public function getMessage(): string
{
return $this->message;
}
public function getTag(): ?string
{
return $this->tag;
}
}
登录后复制
在上面的例子中：
- #[Attribute(…)]：这是关键。它声明MyAttribute类本身是一个Attribute。
- Attribute::TARGET_CLASS | Attribute::TARGET_METHOD：这些常量定义了MyAttribute可以应用于哪些PHP结构。
- TARGET_CLASS：类
- TARGET_METHOD：方法
- TARGET_PROPERTY：属性
- TARGET_FUNCTION：函数
- TARGET_PARAMETER：参数
- TARGET_CLASS_CONSTANT：类常量
- TARGET_ALL：所有上述目标
- Attribute::IS_REPEATABLE：如果设置，表示同一个Attribute可以在同一个目标上多次使用。
- __construct(string $message, ?string $tag = null)：Attribute的构造函数，用于在声明Attribute时接收参数。这些参数将作为元数据被存储。
3. Attributes 的应用与误区
一旦定义了Attribute，就可以在类、方法、属性等PHP结构上使用它。
// 3. 在目标元素上使用Attribute
#[MyAttribute('Hello from SomeClass', 'class-info')]
#[MyAttribute('Another class attribute')] // 允许重复使用
class SomeClass
{
#[MyAttribute('Property attribute', 'field-tag')]
public string $name = 'Default Name';
#[MyAttribute('Method attribute', 'action')]
public function someMethod(
#[MyAttribute('Parameter attribute')] string $param
): void
{
// ...
}
#[MyAttribute('Constant attribute')]
public const MY_CONSTANT = 123;
}
登录后复制
常见误区：Attribute 构造函数不会自动执行
许多初学者会误以为，当一个Attribute被声明在某个类或方法上时，它的构造函数就会立即执行。例如，在上述SomeClass被加载时，MyAttribute的构造函数并不会自动运行。
// 实例化 SomeClass 并不会触发 MyAttribute 的构造函数 $instance = new SomeClass(); // 不会打印 "[DEBUG] MyAttribute 构造函数被调用..."
登录后复制
这是因为Attributes仅仅是元数据。它们就像是贴在代码上的标签，PHP引擎在解析代码时会识别这些标签，但并不会主动去“读取”或“执行”它们。要访问这些元数据，你需要显式地使用PHP的反射（Reflection）API。
4. 通过 Reflection API 访问 Attributes
Reflection API允许你在运行时检查类、方法、属性等的信息，包括它们上面声明的Attributes。这是获取Attribute实例并执行其构造函数的唯一方式。
示例：通过反射访问并实例化 Attributes
<?php
// ... (MyAttribute 和 SomeClass 的定义如上) ...
echo PHP_EOL . "--- 通过反射访问 Attributes ---" . PHP_EOL;
// 1. 访问类的 Attributes
echo "--- 访问 SomeClass 的 Attributes ---" . PHP_EOL;
$reflectionClass = new ReflectionClass(SomeClass::class);
$classAttributes = $reflectionClass->getAttributes();
if (!empty($classAttributes)) {
echo "发现 " . count($classAttributes) . " 个类级别 Attribute." . PHP_EOL;
foreach ($classAttributes as $attribute) {
// $attribute 是一个 ReflectionAttribute 实例
echo "Attribute 名称: " . $attribute->getName() . PHP_EOL;
// 实例化 Attribute 类本身，此时其构造函数会被调用
$myAttributeInstance = $attribute->newInstance();
// 现在你可以调用 Attribute 实例的方法来获取数据
if ($myAttributeInstance instanceof MyAttribute) {
echo " 从 Attribute 实例获取消息: " . $myAttributeInstance->getMessage() . PHP_EOL;
echo " 从 Attribute 实例获取标签: " . ($myAttributeInstance->getTag() ?? '无') . PHP_EOL;
}
}
} else {
echo "SomeClass 没有类级别 Attributes." . PHP_EOL;
}
// 2. 访问方法的 Attributes
echo PHP_EOL . "--- 访问 someMethod 的 Attributes ---" . PHP_EOL;
$reflectionMethod = new ReflectionMethod(SomeClass::class, 'someMethod');
$methodAttributes = $reflectionMethod->getAttributes();
if (!empty($methodAttributes)) {
echo "发现 " . count($methodAttributes) . " 个方法级别 Attribute." . PHP_EOL;
foreach ($methodAttributes as $attribute) {
echo "Attribute 名称: " . $attribute->getName() . PHP_EOL;
$myAttributeInstance = $attribute->newInstance();
if ($myAttributeInstance instanceof MyAttribute) {
echo " 从 Attribute 实例获取消息: " . $myAttributeInstance->getMessage() . PHP_EOL;
echo " 从 Attribute 实例获取标签: " . ($myAttributeInstance->getTag() ?? '无') . PHP_EOL;
}
}
} else {
echo "someMethod 没有方法级别 Attributes." . PHP_EOL;
}
// 3. 访问属性的 Attributes
echo PHP_EOL . "--- 访问 name 属性的 Attributes ---" . PHP_EOL;
$reflectionProperty = new ReflectionProperty(SomeClass::class, 'name');
$propertyAttributes = $reflectionProperty->getAttributes();
if (!empty($propertyAttributes)) {
echo "发现 " . count($propertyAttributes) . " 个属性级别 Attribute." . PHP_EOL;
foreach ($propertyAttributes as $attribute) {
echo "Attribute 名称: " . $attribute->getName() . PHP_EOL;
$myAttributeInstance = $attribute->newInstance();
if ($myAttributeInstance instanceof MyAttribute) {
echo " 从 Attribute 实例获取消息: " . $myAttributeInstance->getMessage() . PHP_EOL;
echo " 从 Attribute 实例获取标签: " . ($myAttributeInstance->getTag() ?? '无') . PHP_EOL;
}
}
} else {
echo "name 属性没有 Attributes." . PHP_EOL;
}
// 4. 访问参数的 Attributes
echo PHP_EOL . "--- 访问 someMethod 参数的 Attributes ---" . PHP_EOL;
$reflectionParameter = new ReflectionParameter([SomeClass::class, 'someMethod'], 'param');
$parameterAttributes = $reflectionParameter->getAttributes();
if (!empty($parameterAttributes)) {
echo "发现 " . count($parameterAttributes) . " 个参数级别 Attribute." . PHP_EOL;
foreach ($parameterAttributes as $attribute) {
echo "Attribute 名称: " . $attribute->getName() . PHP_EOL;
$myAttributeInstance = $attribute->newInstance();
if ($myAttributeInstance instanceof MyAttribute) {
echo " 从 Attribute 实例获取消息: " . $myAttributeInstance->getMessage() . PHP_EOL;
echo " 从 Attribute 实例获取标签: " . ($myAttributeInstance->getTag() ?? '无') . PHP_EOL;
}
}
} else {
echo "someMethod 的参数没有 Attributes." . PHP_EOL;
}
// 5. 访问类常量的 Attributes
echo PHP_EOL . "--- 访问 MY_CONSTANT 类常量的 Attributes ---" . PHP_EOL;
$reflectionClassConstant = new ReflectionClassConstant(SomeClass::class, 'MY_CONSTANT');
$constantAttributes = $reflectionClassConstant->getAttributes();
if (!empty($constantAttributes)) {
echo "发现 " . count($constantAttributes) . " 个类常量级别 Attribute." . PHP_EOL;
foreach ($constantAttributes as $attribute) {
echo "Attribute 名称: " . $attribute->getName() . PHP_EOL;
$myAttributeInstance = $attribute->newInstance();
if ($myAttributeInstance instanceof MyAttribute) {
echo " 从 Attribute 实例获取消息: " . $myAttributeInstance->getMessage() . PHP_EOL;
echo " 从 Attribute 实例获取标签: " . ($myAttributeInstance->getTag() ?? '无') . PHP_EOL;
}
}
} else {
echo "MY_CONSTANT 类常量没有 Attributes." . PHP_EOL;
}
?>
登录后复制
关键步骤解析：
-
创建 Reflection 对象： 根据要检查的目标（类、方法、属性等），创建相应的ReflectionClass、ReflectionMethod、ReflectionProperty、ReflectionParameter或ReflectionClassConstant实例。
- new ReflectionClass(SomeClass::class)
- new ReflectionMethod(SomeClass::class, ‘someMethod’)
- new ReflectionProperty(SomeClass::class, ‘name’)
- new ReflectionParameter([SomeClass::class, ‘someMethod’], ‘param’)
- new ReflectionClassConstant(SomeClass::class, ‘MY_CONSTANT’)
-
获取 Attributes： 调用Reflection对象的getAttributes()方法。它会返回一个ReflectionAttribute对象数组。
- $reflection->getAttributes()
-
实例化 Attribute： 遍历ReflectionAttribute数组。对于每个ReflectionAttribute对象，调用其newInstance()方法。这将执行Attribute类的构造函数，并返回一个该Attribute类的实例。
- $attribute->newInstance()
- 使用 Attribute 实例： 现在你获得了Attribute的真实实例，可以像使用普通对象一样调用其方法，获取其内部存储的元数据。
5. 注意事项与最佳实践
- Attributes 的用途： Attributes主要用于框架、库和工具，它们需要通过元数据来配置行为（例如路由、ORM映射、验证规则、依赖注入等）。在普通的业务逻辑中直接使用Attributes可能并不常见。
- 构造函数副作用： 强烈建议Attributes的构造函数只用于存储数据，避免执行有副作用的操作（如文件写入、网络请求、数据库操作等），除非是调试或框架的特定设计。Attributes的生命周期由反射调用决定，不应依赖于其构造函数来触发业务逻辑。
- Attribute 的目标： 在定义Attribute时，务必通过#[Attribute(Attribute::TARGET_…)]明确指定其可应用的目标类型，这有助于提高代码的健壮性和可读性。
- 重复性： 如果同一个Attribute可能需要在同一目标上多次使用（例如多个验证规则），请确保在定义时加上Attribute::IS_REPEATABLE标志。
- 性能考量： 尽管Attributes的解析是原生的，但频繁地使用反射API（特别是遍历大量类和方法）仍然会带来一定的性能开销。在性能敏感的应用中，可以考虑缓存反射结果。
总结
PHP 8 Attributes为PHP带来了现代化的元数据处理能力，极大地提升了框架和库的表达力与灵活性。理解Attributes作为被动元数据，并通过Reflection API主动访问和实例化它们是掌握其核心的关键。通过本教程，您应该能够自信地定义和使用自定义Attributes，并将其集成到您的PHP应用程序和工具中。
以上就是PHP 8 Attributes 使用指南：从定义到反射访问的详细内容，更多请关注php中文网其它相关文章！