【PHP8.x】ReflectionProperty::getAttributes()メソッドの使い方

Copy
1<?php
2
3// 1. カスタム属性を定義します。
4// #[Attribute] を使うことで、このクラスがPHPの属性として使えるようになります。
5// \Attribute::TARGET_PROPERTY は、この属性がプロパティにのみ適用できることを示します。
6#[Attribute(\Attribute::TARGET_PROPERTY)]
7class MyPropertyAttribute
8{
9    // コンストラクタプロパティプロモーションを使って、属性の引数を定義します。
10    public function __construct(
11        public string $description,
12        public int $level = 0
13    ) {}
14}
15
16// 2. 属性を持つサンプルクラスを定義します。
17class MyClassWithAttributes
18{
19    // プロパティに定義したカスタム属性を適用します。
20    // PHP 8以降では、このように属性を記述できます。
21    #[MyPropertyAttribute(description: "このプロパティは特別な意味を持ちます。", level: 5)]
22    public string $specialProperty = "Hello Reflection!";
23
24    // 別のプロパティ（属性は適用されていません）。
25    public int $normalProperty = 123;
26}
27
28// 3. リフレクションAPIを使用してプロパティの属性情報を取得します。
29
30// まず、対象のクラスをリフレクションします。
31$reflectionClass = new ReflectionClass(MyClassWithAttributes::class);
32
33echo "--- クラス内の全プロパティの属性情報を表示 ---" . PHP_EOL;
34
35// クラス内の全てのプロパティをループ処理します。
36foreach ($reflectionClass->getProperties() as $property) {
37    echo "プロパティ名: " . $property->getName() . PHP_EOL;
38
39    // ReflectionProperty::getAttributes() メソッドを使って、
40    // プロパティに適用されている全ての属性（ReflectionAttributeオブジェクトの配列）を取得します。
41    $attributes = $property->getAttributes();
42
43    if (empty($attributes)) {
44        echo "  このプロパティには属性がありません。" . PHP_EOL;
45    } else {
46        echo "  適用されている属性:" . PHP_EOL;
47        // 取得した各属性の情報を表示します。
48        foreach ($attributes as $attribute) {
49            echo "    - 属性クラス名: " . $attribute->getName() . PHP_EOL;
50
51            // 属性の引数（コンストラクタに渡された値）にアクセスするために、
52            // newInstance() メソッドを使って属性のインスタンスを作成します。
53            try {
54                $attributeInstance = $attribute->newInstance();
55                // 属性が MyPropertyAttribute のインスタンスであれば、そのプロパティにアクセスできます。
56                if ($attributeInstance instanceof MyPropertyAttribute) {
57                    echo "      説明: " . $attributeInstance->description . PHP_EOL;
58                    echo "      レベル: " . $attributeInstance->level . PHP_EOL;
59                }
60            } catch (ReflectionException $e) {
61                echo "      属性インスタンスの作成に失敗しました: " . $e->getMessage() . PHP_EOL;
62            }
63        }
64    }
65    echo PHP_EOL;
66}
67
68echo "--- 特定の属性を持つプロパティをフィルタリングして表示 ---" . PHP_EOL;
69
70// 特定のプロパティをリフレクションします。
71$specificProperty = $reflectionClass->getProperty('specialProperty');
72
73// ReflectionProperty::getAttributes() の最初の引数に属性クラス名を指定することで、
74// 特定の属性（ここでは MyPropertyAttribute）のみをフィルタリングして取得できます。
75$myPropertyAttributes = $specificProperty->getAttributes(MyPropertyAttribute::class);
76
77if (!empty($myPropertyAttributes)) {
78    echo "プロパティ '" . $specificProperty->getName() . "' は 'MyPropertyAttribute' を持っています。" . PHP_EOL;
79    foreach ($myPropertyAttributes as $attribute) {
80        $attributeInstance = $attribute->newInstance();
81        if ($attributeInstance instanceof MyPropertyAttribute) {
82            echo "  説明: " . $attributeInstance->description . PHP_EOL;
83            echo "  レベル: " . $attributeInstance->level . PHP_EOL;
84        }
85    }
86} else {
87    echo "プロパティ '" . $specificProperty->getName() . "' は 'MyPropertyAttribute' を持っていません。" . PHP_EOL;
88}
89
90?>

このサンプルコードは、PHP 8で導入された「属性（Attributes）」という、コードにメタ情報を付与する仕組みを、リフレクションAPIを使ってプログラムが実行時に読み取る方法を解説しています。まず、#[Attribute]キーワードを用いてMyPropertyAttributeというカスタム属性を定義し、これがプロパティにのみ適用できることを示します。次に、このカスタム属性をMyClassWithAttributesクラスの$specialPropertyに適用しています。

コードの核心は、リフレクションAPIを用いてこの属性情報を取得する部分です。ReflectionClassから対象のクラスをリフレクションし、その中から各プロパティ（ReflectionPropertyオブジェクト）を取り出します。ReflectionProperty::getAttributes()メソッドは、そのプロパティに適用されている全ての属性をReflectionAttributeオブジェクトの配列として返します。第一引数$nameにnullを指定すると全ての属性を、特定の属性クラス名（例: MyPropertyAttribute::class）を指定するとその属性のみをフィルタリングして取得できます。第二引数$flagsは属性の検索方法を制御しますが、通常はデフォルトの0を使用します。

取得したReflectionAttributeオブジェクトからは、getName()メソッドで属性のクラス名を知ることができ、newInstance()メソッドを使うことで実際に属性クラスのインスタンスを生成し、属性のコンストラクタに渡された値（例: $descriptionや$level）にアクセスすることが可能です。これにより、プログラムは実行時に自身の構造に関する詳細な情報を動的に取得し、その情報に基づいて振る舞いを変更するといった高度な処理を実現できます。

Copy
1<?php
2
3// PHP 8以降で利用可能なカスタム属性 (Attributes) を定義します。
4// #[Attribute(Attribute::TARGET_PROPERTY)] は、この属性がクラスのプロパティにのみ適用できることを示します。
5#[Attribute(Attribute::TARGET_PROPERTY)]
6class MyDocumentationAttribute
7{
8    public string $description;
9    public string $author;
10
11    /**
12     * @param string $description このプロパティの目的や役割の説明
13     * @param string $author このプロパティを記述した担当者
14     */
15    public function __construct(string $description, string $author = 'Unknown')
16    {
17        $this->description = $description;
18        $this->author = $author;
19    }
20}
21
22// 別のカスタム属性を定義します。これは検証ルールを示すものとします。
23#[Attribute(Attribute::TARGET_PROPERTY)]
24class MyValidationAttribute
25{
26    public int $minLength;
27
28    /**
29     * @param int $minLength このプロパティの文字列の最小長
30     */
31    public function __construct(int $minLength)
32    {
33        $this->minLength = $minLength;
34    }
35}
36
37// カスタム属性が適用されたクラスとプロパティを定義します。
38class User
39{
40    // #[AttributeName(argument1, argument2)] の形式で属性をプロパティに適用します。
41    #[MyDocumentationAttribute('ユーザーの一意な識別子', '開発チームA')]
42    #[MyValidationAttribute(minLength: 5)] // 名前付き引数も使用可能
43    private string $id;
44
45    #[MyDocumentationAttribute('ユーザーの氏名')]
46    private string $name;
47
48    public function __construct(string $id, string $name)
49    {
50        $this->id = $id;
51        $this->name = $name;
52    }
53}
54
55/**
56 * ReflectionProperty::getAttributes() の使用例を示します。
57 * プロパティに適用された属性情報を取得し、表示します。
58 */
59function demonstrateReflectionPropertyAttributes(): void
60{
61    echo "--- ReflectionProperty::getAttributes() のデモンストレーション ---\n\n";
62
63    // UserクラスのReflectionClassオブジェクトを作成します。
64    $reflectionClass = new ReflectionClass(User::class);
65
66    // 'id' プロパティのReflectionPropertyオブジェクトを取得します。
67    $idProperty = $reflectionClass->getProperty('id');
68
69    echo "対象プロパティ: '" . $idProperty->getName() . "'\n";
70    echo "--------------------------------------------------------\n";
71
72    // プロパティに適用されている全ての属性を取得します。
73    // getAttributes() は ReflectionAttribute オブジェクトの配列を返します。
74    $allAttributes = $idProperty->getAttributes();
75
76    echo "取得された属性の総数: " . count($allAttributes) . "\n\n";
77
78    if (count($allAttributes) > 0) {
79        foreach ($allAttributes as $attribute) {
80            echo "  - 属性名: " . $attribute->getName() . "\n";
81
82            // ReflectionAttribute::newInstance() を使用して、属性クラスのインスタンスを生成します。
83            // これにより、属性に渡されたコンストラクタ引数にアクセスできます。
84            $attributeInstance = $attribute->newInstance();
85
86            if ($attributeInstance instanceof MyDocumentationAttribute) {
87                echo "    説明: " . $attributeInstance->description . "\n";
88                echo "    著者: " . $attributeInstance->author . "\n";
89            } elseif ($attributeInstance instanceof MyValidationAttribute) {
90                echo "    最小長: " . $attributeInstance->minLength . "\n";
91            }
92            echo "\n";
93        }
94    } else {
95        echo "このプロパティには属性が適用されていません。\n";
96    }
97
98    echo "--------------------------------------------------------\n\n";
99
100    // getAttributes() の最初の引数 $name を使用して、特定の属性名でフィルタリングする例です。
101    // 指定したクラス名の属性のみが取得されます。
102    echo "--- 特定の属性名でフィルタリングする例 ---\n\n";
103    echo "対象プロパティ: '" . $idProperty->getName() . "' の 'MyDocumentationAttribute' のみを取得\n";
104    echo "--------------------------------------------------------\n";
105
106    $specificAttributes = $idProperty->getAttributes(MyDocumentationAttribute::class);
107    echo "取得された 'MyDocumentationAttribute' の数: " . count($specificAttributes) . "\n\n";
108
109    foreach ($specificAttributes as $attribute) {
110        echo "  - 属性名: " . $attribute->getName() . "\n";
111        $attributeInstance = $attribute->newInstance();
112        if ($attributeInstance instanceof MyDocumentationAttribute) {
113            echo "    説明: " . $attributeInstance->description . "\n";
114            echo "    著者: " . $attributeInstance->author . "\n";
115        }
116        echo "\n";
117    }
118    echo "--------------------------------------------------------\n";
119}
120
121// 上記のデモンストレーション関数を実行します。
122demonstrateReflectionPropertyAttributes();

PHP 8で導入された「属性（Attributes）」は、クラスやプロパティなどに付加的な情報（メタデータ）を埋め込むための機能です。ReflectionProperty::getAttributes()メソッドは、この属性にアクセスし、プログラムからその情報を動的に取得するために使用されます。

このメソッドは、指定されたプロパティに適用されているすべての属性を配列として返します。戻り値はReflectionAttributeオブジェクトの配列で、各オブジェクトは属性の名前やコンストラクタ引数などの詳細な情報を含んでいます。

引数$nameには、取得したい属性のクラス名を指定できます。この引数を使用すると、特定の種類の属性のみをフィルタリングして取得することが可能です。引数$flagsは属性の検索方法を調整するもので、通常はデフォルトのままで問題ありません。

サンプルコードでは、UserクラスのidプロパティにMyDocumentationAttributeとMyValidationAttributeというカスタム属性が適用されています。getAttributes()を呼び出すと、これらの属性情報がReflectionAttributeオブジェクトとして取得され、newInstance()メソッドを使って属性クラスの実際のインスタンスを生成し、その中に含まれるdescriptionやminLengthといった具体的な値にアクセスしています。また、MyDocumentationAttribute::classを$name引数に渡すことで、特定の属性のみを取得する例も確認でき、コード実行時にプロパティの付加情報を柔軟に利用できることを示しています。