PHP attributes() 函数详解
在PHP 8.0及以上版本中，引入了全新的属性（Attributes）特性，它允许开发者通过结构化元数据为类、方法、属性等添加注解信息，无需依赖传统注释解析。而attributes()方法则是获取这些属性实例的核心接口，本文将系统讲解其用法、特性及实战场景。
一、函数基本概念
attributes()是PHP反射API中的通用方法，可在ReflectionClass、ReflectionMethod、ReflectionProperty等反射类实例上调用，用于获取目标元素上定义的所有属性。它返回的是ReflectionAttribute对象的数组，通过这些对象可以进一步获取属性的名称、参数等信息。
注意：该方法是PHP 8.0+的新特性，低版本PHP无法使用。
二、基础语法与参数
方法的通用语法如下：
public ReflectionAttribute[] ReflectionClass::attributes( string $name = null, int $flags = 0 )
参数说明：
name（可选）：指定要筛选的属性类名，仅返回匹配该名称的属性。如果为null，则返回所有属性。
flags（可选）：筛选标志，目前仅支持
ReflectionAttribute::IS_INSTANCEOF，用于匹配当前类或其子类的属性。
三、基础使用示例
首先定义一个自定义属性类，再将其应用到目标元素上，最后通过反射调用attributes()获取属性信息。
1. 定义自定义属性
自定义属性类需要标记#[Attribute]属性，才能作为合法属性使用：
<?php
// 定义自定义属性类，标记#[Attribute]使其可作为属性使用
#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD)]
class MyAttribute
{
public function __construct(
public string $description,
public int $priority = 0
) {}
}2. 为类和方法添加属性
使用#[属性名(参数)]的语法为目标元素添加属性：
<?php
// 为类添加属性
#[MyAttribute(description: "这是一个测试类", priority: 1)]
class TestClass
{
// 为方法添加属性
#[MyAttribute(description: "这是一个测试方法")]
public function testMethod(): void
{
echo "test";
}
}3. 调用attributes()获取属性
通过反射类获取目标元素后，调用attributes()方法：
<?php
$refClass = new ReflectionClass(TestClass::class);
// 获取类的所有属性
$classAttrs = $refClass->attributes();
echo "类的属性数量：" . count($classAttrs) . PHP_EOL;
foreach ($classAttrs as $attr) {
// 获取属性名称
echo "属性名称：" . $attr->getName() . PHP_EOL;
// 获取属性实例（调用newInstance()会执行属性类的构造函数）
$attrInstance = $attr->newInstance();
echo "属性描述：" . $attrInstance->description . PHP_EOL;
echo "属性优先级：" . $attrInstance->priority . PHP_EOL;
}
// 获取方法的属性
$refMethod = $refClass->getMethod('testMethod');
$methodAttrs = $refMethod->attributes(MyAttribute::class);
echo "方法匹配的MyAttribute属性数量：" . count($methodAttrs) . PHP_EOL;上述代码执行后输出结果：
类的属性数量：1 属性名称：MyAttribute 属性描述：这是一个测试类 属性优先级：1 方法匹配的MyAttribute属性数量：1
四、进阶用法说明
1. 筛选特定属性
如果需要只获取某一类属性，可以传入name参数，避免额外遍历：
<?php $refClass = new ReflectionClass(TestClass::class); // 仅获取MyAttribute类型的属性 $myAttrs = $refClass->attributes(MyAttribute::class);
2. 使用flags参数匹配子类属性
如果自定义属性存在继承关系，可以使用ReflectionAttribute::IS_INSTANCEOF标志匹配所有子类属性：
<?php
class BaseAttribute {}
class ChildAttribute extends BaseAttribute {}
#[ChildAttribute]
class AnotherClass {}
$refClass = new ReflectionClass(AnotherClass::class);
// 匹配BaseAttribute及其子类的属性
$attrs = $refClass->attributes(BaseAttribute::class, ReflectionAttribute::IS_INSTANCEOF);
echo "匹配的属性数量：" . count($attrs) . PHP_EOL; // 输出13. 避免重复实例化
newInstance()每次调用都会创建新的属性实例，如果需要复用，建议将结果缓存：
<?php
$refClass = new ReflectionClass(TestClass::class);
$classAttrs = $refClass->attributes();
$attrInstances = [];
foreach ($classAttrs as $attr) {
$attrInstances[$attr->getName()] = $attr->newInstance();
}五、实际应用场景
attributes()函数在以下场景中非常实用：
路由定义：框架中通过属性标记控制器方法对应的路由地址，运行时通过反射获取属性生成路由表。
权限校验：为需要权限验证的方法添加属性，执行前通过反射获取属性判断当前用户是否有权限访问。
数据验证：为模型属性添加验证规则属性，保存数据时通过反射获取属性执行对应验证逻辑。
依赖注入：标记需要注入的依赖类，容器通过反射获取属性自动完成依赖注入。
六、注意事项
只有PHP 8.0及以上版本支持属性特性，使用时需确认运行环境版本。
属性类的构造函数参数需要与定义属性时传入的参数对应，否则调用
newInstance()时会抛出异常。attributes()返回的是ReflectionAttribute数组，不是属性类的实例，需要调用newInstance()才能获取可用对象。属性仅作为元数据存在，不会主动执行任何逻辑，需要在业务代码中主动通过反射获取并处理。