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

Copy
1<?php
2
3// PHP 8以降で導入されたアトリビュートを定義します。
4// #[Attribute] アトリビュート自体もアトリビュートで修飾できます。
5// Attribute::TARGET_METHOD はこのアトリビュートがメソッドにのみ適用可能であることを示します。
6// Attribute::IS_REPEATABLE は同じアトリビュートを複数回適用できることを示します。
7#[Attribute(Attribute::TARGET_METHOD | Attribute::IS_REPEATABLE)]
8class MyCustomAttribute
9{
10    // アトリビュートのコンストラクタで引数を受け取ります。
11    public function __construct(public string $message) {}
12}
13
14// もう一つ別のアトリビュートを定義します。
15#[Attribute(Attribute::TARGET_METHOD)]
16class AnotherMethodAttribute
17{
18    public function __construct(public int $id) {}
19}
20
21// アトリビュートが付与される対象のクラスとメソッドを定義します。
22class MyService
23{
24    // processDataメソッドに定義したアトリビュートを付与します。
25    #[MyCustomAttribute("Hello from PHP 8!")]
26    #[MyCustomAttribute("Welcome to Reflection!")]
27    #[AnotherMethodAttribute(id: 42)]
28    public function processData(): string
29    {
30        return "Data processed.";
31    }
32
33    public function getStatus(): string
34    {
35        return "Service is running.";
36    }
37}
38
39// ReflectionClass を使用して MyService クラスのリフレクションオブジェクトを作成します。
40$reflectionClass = new ReflectionClass(MyService::class);
41
42// processData メソッドの ReflectionMethod オブジェクトを取得します。
43$reflectionMethod = $reflectionClass->getMethod('processData');
44
45echo "--- processData() メソッドに付与された全てのアトリビュート ---\n";
46
47// getAttributes() を引数なしで呼び出すと、メソッドに付与された全てのアトリビュートが取得できます。
48// 戻り値は ReflectionAttribute オブジェクトの配列です。
49$allAttributes = $reflectionMethod->getAttributes();
50
51if (empty($allAttributes)) {
52    echo "アトリビュートは見つかりませんでした。\n";
53} else {
54    foreach ($allAttributes as $attribute) {
55        // アトリビュートの完全修飾名を取得します。
56        echo "アトリビュート名: " . $attribute->getName() . "\n";
57
58        // アトリビュートの引数を配列で取得します。
59        echo "引数: " . json_encode($attribute->getArguments()) . "\n";
60
61        // アトリビュートクラスのインスタンスを作成します。
62        // これにより、アトリビュートのコンストラクタで設定されたプロパティにアクセスできます。
63        $instance = $attribute->newInstance();
64
65        if ($instance instanceof MyCustomAttribute) {
66            echo "  -> MyCustomAttribute のメッセージ: " . $instance->message . "\n";
67        } elseif ($instance instanceof AnotherMethodAttribute) {
68            echo "  -> AnotherMethodAttribute のID: " . $instance->id . "\n";
69        }
70        echo "------\n";
71    }
72}
73
74echo "\n--- MyCustomAttribute 型のアトリビュートのみを取得 ---\n";
75
76// getAttributes() の第一引数にアトリビュートのクラス名を指定すると、
77// その型のアトリビュートのみをフィルタリングして取得できます。
78$myCustomTypeAttributes = $reflectionMethod->getAttributes(MyCustomAttribute::class);
79
80if (empty($myCustomTypeAttributes)) {
81    echo "MyCustomAttribute 型のアトリビュートは見つかりませんでした。\n";
82} else {
83    foreach ($myCustomTypeAttributes as $attribute) {
84        echo "アトリビュート名: " . $attribute->getName() . "\n";
85        $instance = $attribute->newInstance();
86        echo "  -> メッセージ: " . $instance->message . "\n";
87    }
88}
89
90?>

「ReflectionMethod::getAttributes」は、PHP 8で導入された「アトリビュート」を、リフレクション機能を使ってメソッドから動的に取得するためのメソッドです。これにより、実行時にコードの構造を詳細に解析できます。

このメソッドを引数なしで呼び出すと、対象のメソッドに付与されている全てのアトリビュートが「ReflectionAttribute」オブジェクトの配列として返されます。各「ReflectionAttribute」オブジェクトからは、「getName()」でアトリビュートの完全修飾名を取得したり、「getArguments()」でアトリビュートに渡された引数を取得できます。さらに、「newInstance()」メソッドを使用すると、アトリビュートクラスのインスタンスを生成し、そのプロパティ（コンストラクタで定義されたもの）にアクセスすることが可能です。

第一引数にアトリビュートのクラス名（例: MyCustomAttribute::class）を指定すると、その型のアトリビュートのみをフィルタリングして取得できます。これにより、特定の型のアトリビュートのみに関心がある場合に便利です。サンプルコードでは、まずprocessDataメソッドに付与された全てのアトリビュートを取得し、その後にMyCustomAttribute型のアトリビュートだけを抽出して情報を取り出しています。この機能は、フレームワークやライブラリがユーザー定義のアトリビュートを解析し、振る舞いを変更する際などに活用されます。

Copy
1<?php
2
3// 1. カスタムAttributeの定義
4// PHP 8で導入されたAttributeは、コードのメタデータを追加する機能です。
5// #[Attribute(Attribute::TARGET_METHOD)] は、このAttributeがメソッドにのみ適用できることを示します。
6#[Attribute(Attribute::TARGET_METHOD)]
7class MyTaskInfo
8{
9    public function __construct(
10        public string $description,
11        public int $priority = 0,
12        public bool $isCritical = false
13    ) {
14    }
15}
16
17// 2. Attributeを適用するクラスとメソッドの定義
18class TaskService
19{
20    // MyTaskInfo Attributeをメソッドに適用します。
21    // ここでAttributeのコンストラクタに値を渡しています。
22    #[MyTaskInfo("システムの重要なタスクを処理します。", priority: 1, isCritical: true)]
23    public function processCriticalTask(): void
24    {
25        echo "クリティカルなタスクを実行中...\n";
26    }
27
28    // Attributeが適用されていないメソッドも用意します。
29    public function processRegularTask(): void
30    {
31        echo "通常のタスクを実行中...\n";
32    }
33}
34
35/**
36 * ReflectionMethod::getAttributes() の使用例を示します。
37 * この関数は、指定されたメソッドに適用されているAttributeの情報を取得します。
38 */
39function demonstrateReflectionMethodGetAttributes(): void
40{
41    echo "--- ReflectionMethod::getAttributes() デモンストレーション ---\n\n";
42
43    // 1. TaskService クラスのリフレクションオブジェクトを作成
44    //    リフレクションは、実行時にクラスやメソッド、プロパティなどの情報を
45    //    調べたり、操作したりするための機能です。
46    $reflector = new ReflectionClass(TaskService::class);
47
48    // 2. 'processCriticalTask' メソッドのリフレクションオブジェクトを取得
49    //    このメソッドには MyTaskInfo Attribute が適用されています。
50    $methodWithAttribute = $reflector->getMethod('processCriticalTask');
51
52    echo "対象メソッド: '" . $methodWithAttribute->getName() . "'\n";
53    echo "---------------------------------------------------\n";
54
55    // 3. getAttributes() を呼び出して、このメソッドに適用されているAttributeを取得
56    //    引数なしの場合、適用されている全てのAttributeが取得されます。
57    //    戻り値は ReflectionAttribute オブジェクトの配列です。
58    $attributes = $methodWithAttribute->getAttributes();
59
60    if (empty($attributes)) {
61        echo "このメソッドにはAttributeが適用されていません。\n";
62    } else {
63        echo "取得されたAttribute:\n";
64        // 取得されたAttributeをループで処理します
65        foreach ($attributes as $attribute) {
66            echo "  - Attributeクラス名: " . $attribute->getName() . "\n";
67
68            // Attributeのコンストラクタに渡された引数を取得します。
69            $arguments = $attribute->getArguments();
70            if (!empty($arguments)) {
71                echo "    引数:\n";
72                foreach ($arguments as $name => $value) {
73                    echo "      " . (is_string($name) ? $name . ": " : "") . var_export($value, true) . "\n";
74                }
75            } else {
76                echo "    引数: (なし)\n";
77            }
78
79            // Attributeのインスタンスを生成して、プロパティにアクセスすることも可能です。
80            // $instance = $attribute->newInstance();
81            // echo "    Description (from instance): " . $instance->description . "\n";
82        }
83    }
84
85    echo "\n--- Attributeが適用されていないメソッドの確認 ---\n";
86    // 'processRegularTask' メソッドのリフレクションオブジェクトを取得
87    // このメソッドにはAttributeが適用されていません。
88    $methodWithoutAttribute = $reflector->getMethod('processRegularTask');
89    echo "対象メソッド: '" . $methodWithoutAttribute->getName() . "'\n";
90    echo "---------------------------------------------------\n";
91
92    $noAttributes = $methodWithoutAttribute->getAttributes();
93    if (empty($noAttributes)) {
94        echo "このメソッドにはAttributeが適用されていません。\n";
95    }
96}
97
98// デモンストレーション関数を実行します。
99demonstrateReflectionMethodGetAttributes();
100
101?>

PHPのReflectionMethod::getAttributes()メソッドは、PHP 8で導入されたAttribute（アトリビュート）という、コードにメタデータ（付加情報）を追加する機能を実行時に取得するためのものです。リフレクションとは、実行中のプログラム自身の構造を調べたり操作したりする機能です。このメソッドを使うと、特定のクラスメソッドにどんなAttributeが適用されているかを詳細に調べることができます。

このメソッドは、ReflectionClassから取得したReflectionMethodオブジェクトに対して呼び出されます。引数として、取得したいAttributeの完全修飾名を文字列$nameで指定すると、特定のAttributeのみをフィルタリングして取得できます。また、$flags引数には、例えばReflectionAttribute::IS_INSTANCEOFのような定数を指定することで、Attributeの継承関係を考慮した検索も可能です。

戻り値は、メソッドに適用されている各Attributeを表すReflectionAttributeオブジェクトの配列です。もしAttributeが一つも適用されていなければ、空の配列が返されます。取得したReflectionAttributeオブジェクトからは、Attributeのクラス名や、Attributeのコンストラクタに渡された引数の値などを動的に読み取ることができます。これにより、サンプルコードのように、メソッドに定義されたタスクの説明や優先度といった情報をプログラムで活用し、実行時の振る舞いを柔軟に変更するといった応用が可能になります。