PHP 8 Attributes 使用指南：从定义到反射访问

<?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;
    }
}

// 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;
}

// 实例化 SomeClass 并不会触发 MyAttribute 的构造函数
$instance = new SomeClass(); // 不会打印 "[DEBUG] MyAttribute 构造函数被调用..."

<?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;
}

?>