PHP 8 Attributes 简介
在php 8之前，开发者通常依赖phpdoc注释来为代码元素（如类、方法、属性）添加元数据。然而，phpdoc本质上是字符串，解析复杂且不具备结构化校验能力。php 8 attributes（属性）的引入，彻底改变了这一现状。attributes提供了一种原生、结构化的方式来声明元数据，它们是真正的php语言结构，可以被ide、静态分析工具以及运行时反射api识别和处理。
Attributes的主要优势包括：
- 结构化：它们是PHP类，拥有明确的结构和类型。
- 可验证性：可以在定义时通过类型提示等进行校验。
- 运行时可访问性：通过反射API，可以在运行时动态获取和处理这些元数据。
自定义 Attributes 的声明与应用
要创建一个自定义Attribute，你需要定义一个普通的PHP类，并使用内置的#[Attribute]属性来标记它。这个标记告诉PHP引擎，该类是一个Attribute，可以在代码中作为元数据使用。
1. 声明一个Attribute类
Attribute类可以像普通类一样包含构造函数，用于在实例化时接收参数。这些参数就是Attribute的元数据值。
立即学习“PHP免费学习笔记（深入）”；
<?php
use Attribute;
// 使用 #[Attribute] 标记 MyAttribute 类，使其成为一个有效的 Attribute
#[Attribute]
class MyAttribute
{
private string $message;
public function __construct(string $message)
{
$this->message = $message;
// 注意：这里的 echo $message; 在 Attribute 被应用时不会自动执行
// 只有当 Attribute 通过反射被实例化时，构造函数才会执行。
// 为了演示，我们暂时不在这里输出，而是通过 getter 获取。
}
public function getMessage(): string
{
return $this->message;
}
}2. 应用Attribute到代码元素
Attribute可以应用到多种代码元素上，包括类、方法、属性、函数、类常量和参数。使用#[]语法将其放置在目标元素声明之前。
<?php
// ... (MyAttribute class definition from above)
#[MyAttribute('Hello from SomeClass!')]
class SomeClass
{
#[MyAttribute('This is a property attribute')]
public string $name;
#[MyAttribute('Method attribute example')]
public function doSomething(
#[MyAttribute('Parameter attribute')] string $param
): void
{
// ...
}
}
// 也可以应用到函数
#[MyAttribute('Global function attribute')]
function myGlobalFunction(): void
{
// ...
}通过反射机制访问 Attributes
这是理解Attributes工作原理的关键。当你在代码中应用一个Attribute时，它的构造函数并不会立即执行。Attributes本质上是编译时的元数据标记，它们被存储在PHP的内部结构中。要访问这些元数据并在运行时处理它们（包括实例化Attribute类并执行其构造函数），你必须使用PHP的反射（Reflection）API。
1. 获取反射对象
首先，你需要创建一个目标代码元素的反射对象。PHP提供了多种反射类：
- ReflectionClass：用于类。
- ReflectionMethod：用于类方法。
- ReflectionProperty：用于类属性。
- ReflectionFunction：用于函数。
- ReflectionParameter：用于参数。
- ReflectionClassConstant：用于类常量。
<?php
// ... (MyAttribute 和 SomeClass 的定义)
// 针对类获取反射对象
$reflectionClass = new ReflectionClass(SomeClass::class);
// 针对方法获取反射对象
$reflectionMethod = new ReflectionClass(SomeClass::class)->getMethod('doSomething');
// 针对属性获取反射对象
$reflectionProperty = new ReflectionClass(SomeClass::class)->getProperty('name');
// 针对参数获取反射对象
$reflectionParameter = $reflectionMethod->getParameters()[0]; // 获取 doSomething 方法的第一个参数2. 获取 Attributes 列表
所有反射对象都提供一个getAttributes()方法，它返回一个ReflectionAttribute对象的数组。每个ReflectionAttribute对象代表一个已应用的Attribute。
// 获取 SomeClass 上的所有 Attributes $classAttributes = $reflectionClass->getAttributes(); // 获取 doSomething 方法上的所有 Attributes $methodAttributes = $reflectionMethod->getAttributes(); // 获取 name 属性上的所有 Attributes $propertyAttributes = $reflectionProperty->getAttributes(); // 获取 doSomething 方法第一个参数上的所有 Attributes $parameterAttributes = $reflectionParameter->getAttributes();
3. 实例化 Attribute 对象
ReflectionAttribute对象本身并不是你定义的MyAttribute实例，它只是一个描述Attribute的元数据对象。要获取MyAttribute的实例并执行其构造函数，你需要调用ReflectionAttribute对象的newInstance()方法。
// 假设 SomeClass 上只有一个 MyAttribute
if (!empty($classAttributes)) {
$firstClassAttribute = $classAttributes[0]; // 获取第一个 ReflectionAttribute 对象
// 此时才调用 MyAttribute 的构造函数，并返回 MyAttribute 的实例
$myAttributeInstance = $firstClassAttribute->newInstance();
echo "Class Attribute Message: " . $myAttributeInstance->getMessage() . PHP_EOL; // 输出: Class Attribute Message: Hello from SomeClass!
}
// 获取 doSomething 方法上的 MyAttribute
$methodAttribute = $methodAttributes[0]->newInstance();
echo "Method Attribute Message: " . $methodAttribute->getMessage() . PHP_EOL; // 输出: Method Attribute Message: Method attribute example
// 获取 name 属性上的 MyAttribute
$propertyAttribute = $propertyAttributes[0]->newInstance();
echo "Property Attribute Message: " . $propertyAttribute->getMessage() . PHP_EOL; // 输出: Property Attribute Message: This is a property attribute
// 获取 doSomething 方法第一个参数上的 MyAttribute
$parameterAttribute = $parameterAttributes[0]->newInstance();
echo "Parameter Attribute Message: " . $parameterAttribute->getMessage() . PHP_EOL; // 输出: Parameter Attribute Message: Parameter attribute完整示例代码：
<?php
use Attribute;
use ReflectionClass;
// 1. 定义一个自定义 Attribute 类
#[Attribute]
class MyAttribute
{
private string $message;
public function __construct(string $message)
{
$this->message = $message;
// 构造函数在这里被调用，但只有通过反射实例化时才会执行
// echo "MyAttribute constructor called with: " . $message . PHP_EOL;
}
public function getMessage(): string
{
return $this->message;
}
}
// 2. 将 Attribute 应用到代码元素
#[MyAttribute('Hello from SomeClass!')]
class SomeClass
{
#[MyAttribute('This is a property attribute')]
public string $name = 'Default Name';
#[MyAttribute('Method attribute example')]
public function doSomething(
#[MyAttribute('Parameter attribute')] string $param
): void
{
echo "Inside doSomething method." . PHP_EOL;
}
}
// 3. 使用反射机制访问并实例化 Attributes
echo "--- Accessing Class Attributes ---" . PHP_EOL;
$reflectionClass = new ReflectionClass(SomeClass::class);
$classAttributes = $reflectionClass->getAttributes(MyAttribute::class); // 可以指定获取特定类型的 Attribute
foreach ($classAttributes as $reflectionAttribute) {
// 实例化 Attribute 对象，此时 MyAttribute 的构造函数被调用
$myAttributeInstance = $reflectionAttribute->newInstance();
echo "Class Attribute Message: " . $myAttributeInstance->getMessage() . PHP_EOL;
}
echo PHP_EOL . "--- Accessing Property Attributes ---" . PHP_EOL;
$reflectionProperty = $reflectionClass->getProperty('name');
$propertyAttributes = $reflectionProperty->getAttributes(MyAttribute::class);
foreach ($propertyAttributes as $reflectionAttribute) {
$myAttributeInstance = $reflectionAttribute->newInstance();
echo "Property Attribute Message: " . $myAttributeInstance->getMessage() . PHP_EOL;
}
echo PHP_EOL . "--- Accessing Method Attributes ---" . PHP_EOL;
$reflectionMethod = $reflectionClass->getMethod('doSomething');
$methodAttributes = $reflectionMethod->getAttributes(MyAttribute::class);
foreach ($methodAttributes as $reflectionAttribute) {
$myAttributeInstance = $reflectionAttribute->newInstance();
echo "Method Attribute Message: " . $myAttributeInstance->getMessage() . PHP_EOL;
}
echo PHP_EOL . "--- Accessing Parameter Attributes ---" . PHP_EOL;
$reflectionParameter = $reflectionMethod->getParameters()[0]; // 获取 doSomething 方法的第一个参数
$parameterAttributes = $reflectionParameter->getAttributes(MyAttribute::class);
foreach ($parameterAttributes as $reflectionAttribute) {
$myAttributeInstance = $reflectionAttribute->newInstance();
echo "Parameter Attribute Message: " . $myAttributeInstance->getMessage() . PHP_EOL;
}
/*
预期输出：
--- Accessing Class Attributes ---
Class Attribute Message: Hello from SomeClass!
--- Accessing Property Attributes ---
Property Attribute Message: This is a property attribute
--- Accessing Method Attributes ---
Method Attribute Message: Method attribute example
--- Accessing Parameter Attributes ---
Parameter Attribute Message: Parameter attribute
*/注意事项与最佳实践
- Attribute 构造函数不会自动执行：这是最常见的误解。Attribute的应用只是声明元数据，其构造函数只有在通过反射显式调用newInstance()时才会执行。
- #[Attribute]是必须的：只有标记了#[Attribute]的类才能作为Attribute使用。
- Attribute的参数：Attribute的构造函数可以接收任意类型的参数，这些参数就是你希望存储的元数据。
- ReflectionAttribute与Attribute实例：ReflectionAttribute是反射API提供的一个代理对象，它包含Attribute的名称、参数等信息。你需要通过newInstance()方法才能获得自定义Attribute类的真实实例。
- 指定Attribute类型：getAttributes()方法可以接受一个可选的类名参数，用于只获取特定类型的Attribute，这有助于过滤和提高效率。
- 错误处理：在访问getAttributes()返回的数组时，务必检查数组是否为空，以避免索引越界错误。
- 应用场景：Attributes非常适合用于框架、ORM、路由、验证、权限控制等场景，它们提供了一种清晰、可扩展的方式来定义和处理代码行为的元数据。
总结
PHP 8 Attributes为开发者提供了一种强大且优雅的元数据处理机制。通过结合反射API，我们可以在运行时动态地检查、提取和利用这些元数据，从而实现更灵活、更智能的应用程序逻辑。理解Attributes作为编译时元数据与反射机制在运行时实例化和处理它们之间的关系，是有效利用这一新特性的关键。
