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

Copy
1<?php
2
3/**
4 * ビットマスクで表現された属性ターゲットを、人間が読める文字列に変換するヘルパー関数。
5 *
6 * @param int $mask Attribute::TARGET_* 定数のビットマスク
7 * @return string 解釈されたターゲット文字列
8 */
9function getTargetString(int $mask): string
10{
11    $targets = [];
12    if ($mask & Attribute::TARGET_CLASS) {
13        $targets[] = 'クラス';
14    }
15    if ($mask & Attribute::TARGET_FUNCTION) {
16        $targets[] = '関数';
17    }
18    if ($mask & Attribute::TARGET_METHOD) {
19        $targets[] = 'メソッド';
20    }
21    if ($mask & Attribute::TARGET_PROPERTY) {
22        $targets[] = 'プロパティ';
23    }
24    if ($mask & Attribute::TARGET_CLASS_CONSTANT) {
25        $targets[] = 'クラス定数';
26    }
27    if ($mask & Attribute::TARGET_PARAMETER) {
28        $targets[] = 'パラメータ';
29    }
30    if ($mask & Attribute::TARGET_ALL) {
31        // TARGET_ALL が含まれる場合、他の具体的なターゲットも含まれるが、
32        // 初心者向けには「全て」と示すのが最も簡潔。
33        // ただし、通常は TARGET_ALL を指定すると他の具体的なターゲットの指定は不要。
34        // ここでは教育的な目的で全ての可能性を列挙しています。
35        if (count($targets) === 0) { // 他の具体的なターゲットが指定されていない場合のみ表示
36            $targets[] = '全て';
37        }
38    }
39    // PHP 8.1以降で追加された Attribute::TARGET_ENUM などは、必要に応じて追加してください。
40
41    return empty($targets) ? '不明なターゲット' : implode(', ', $targets);
42}
43
44/**
45 * カスタム属性の定義。
46 * この属性は、クラス、メソッド、プロパティに適用できると定義されています。
47 */
48#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD | Attribute::TARGET_PROPERTY)]
49class MyCustomAttribute
50{
51    /**
52     * @param string $description この属性が何を示すかの説明
53     */
54    public function __construct(public string $description) {}
55}
56
57/**
58 * MyCustomAttribute を適用するサンプルクラス。
59 * ここで定義された属性がどのように利用されるかを示します。
60 */
61#[MyCustomAttribute("このクラスは重要な設定を含みます")]
62class MySampleClass
63{
64    #[MyCustomAttribute("このメソッドはユーザーデータを処理します")]
65    public function processUserData(): void
66    {
67        echo "ユーザーデータ処理ロジックを実行中..." . PHP_EOL;
68    }
69
70    #[MyCustomAttribute("このプロパティはユーザーの識別子です")]
71    public string $userId = 'guest_123';
72}
73
74echo "--- ReflectionAttribute::getTarget() の使用例 ---" . PHP_EOL . PHP_EOL;
75
76// MySampleClass のリフレクションオブジェクトを作成
77$reflectionClass = new ReflectionClass(MySampleClass::class);
78
79// 1. クラスに適用された MyCustomAttribute から getTarget() を呼び出す
80echo "【クラス 'MySampleClass' に適用された 'MyCustomAttribute' の情報】" . PHP_EOL;
81$classAttributes = $reflectionClass->getAttributes(MyCustomAttribute::class);
82if (!empty($classAttributes)) {
83    $reflectionAttribute = $classAttributes[0];
84    echo "  属性名: " . $reflectionAttribute->getName() . PHP_EOL;
85    // getTarget() は、この属性がどのPHP要素に適用できるかを定義するビットマスクを返します。
86    echo "  getTarget() の戻り値 (ビットマスク): " . $reflectionAttribute->getTarget() . PHP_EOL;
87    echo "  (解釈): " . getTargetString($reflectionAttribute->getTarget()) . PHP_EOL;
88    echo "  属性の引数 (説明): " . $reflectionAttribute->newInstance()->description . PHP_EOL;
89} else {
90    echo "  クラスに 'MyCustomAttribute' は見つかりませんでした。" . PHP_EOL;
91}
92echo PHP_EOL;
93
94// 2. メソッドに適用された MyCustomAttribute から getTarget() を呼び出す
95echo "【メソッド 'processUserData' に適用された 'MyCustomAttribute' の情報】" . PHP_EOL;
96$reflectionMethod = $reflectionClass->getMethod('processUserData');
97$methodAttributes = $reflectionMethod->getAttributes(MyCustomAttribute::class);
98if (!empty($methodAttributes)) {
99    $reflectionAttribute = $methodAttributes[0];
100    echo "  属性名: " . $reflectionAttribute->getName() . PHP_EOL;
101    // メソッドに適用されていても、getTarget() は属性定義時のターゲットを返します。
102    echo "  getTarget() の戻り値 (ビットマスク): " . $reflectionAttribute->getTarget() . PHP_EOL;
103    echo "  (解釈): " . getTargetString($reflectionAttribute->getTarget()) . PHP_EOL;
104    echo "  属性の引数 (説明): " . $reflectionAttribute->newInstance()->description . PHP_EOL;
105} else {
106    echo "  メソッド 'processUserData' に 'MyCustomAttribute' は見つかりませんでした。" . PHP_EOL;
107}
108echo PHP_EOL;
109
110// 3. プロパティに適用された MyCustomAttribute から getTarget() を呼び出す
111echo "【プロパティ '$reflectionClass->name::userId' に適用された 'MyCustomAttribute' の情報】" . PHP_EOL;
112$reflectionProperty = $reflectionClass->getProperty('userId');
113$propertyAttributes = $reflectionProperty->getAttributes(MyCustomAttribute::class);
114if (!empty($propertyAttributes)) {
115    $reflectionAttribute = $propertyAttributes[0];
116    echo "  属性名: " . $reflectionAttribute->getName() . PHP_EOL;
117    // プロパティに適用されていても、getTarget() は属性定義時のターゲットを返します。
118    echo "  getTarget() の戻り値 (ビットマスク): " . $reflectionAttribute->getTarget() . PHP_EOL;
119    echo "  (解釈): " . getTargetString($reflectionAttribute->getTarget()) . PHP_EOL;
120    echo "  属性の引数 (説明): " . $reflectionAttribute->newInstance()->description . PHP_EOL;
121} else {
122    echo "  プロパティ 'userId' に 'MyCustomAttribute' は見つかりませんでした。" . PHP_EOL;
123}
124echo PHP_EOL;
125
126echo "--- 補足情報 ---" . PHP_EOL;
127echo "ReflectionAttribute::getTarget() メソッドは、その属性自身がどのPHP要素" . PHP_EOL;
128echo "（クラス、関数、メソッド、プロパティなど）に適用できるかを定義した情報" . PHP_EOL;
129echo "（つまり、属性の定義時に #[Attribute(...)] の引数で指定されたターゲット）を返します。" . PHP_EOL;
130echo "これは、実際に属性が適用されたPHP要素のタイプとは直接関係ありません。" . PHP_EOL;

PHP 8で導入された「属性（Attributes）」の情報を取得するReflectionAttributeクラスには、getTarget()というメソッドがあります。このメソッドは引数を持たず、整数（int）を戻り値として返します。戻り値の整数はビットマスクと呼ばれる形式で、その属性自体が「クラス」「関数」「メソッド」「プロパティ」といった、どのPHP要素に適用できるかを定義した情報を示しています。

重要な点として、getTarget()が返すのは、その属性が定義された際に「どこに適用できるか」と指定されたターゲットです。これは、実際にその属性がコード内のどこに適用されているかを示すものではありません。例えば、ある属性がメソッドに適用されていても、getTarget()は属性の定義時に指定された「この属性はクラスにもプロパティにも使える」という情報全体を返します。この機能により、プログラマは定義済みの属性の適用ルールをプログラムから確認し、属性の誤用防止やツール開発に役立てることができます。

Copy
1<?php
2
3// 属性を定義するクラスです。
4// PHP 8では、`#[Attribute]`構文を使ってカスタム属性（アノテーション）を作成できます。
5// `Attribute::TARGET_CLASS`と`Attribute::TARGET_METHOD`は、
6// この`MyCustomAttribute`がクラスとメソッドに適用できることを宣言しています。
7// ReflectionAttribute::getTarget()は、実際にこの属性が適用された要素のタイプを返します。
8#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD)]
9class MyCustomAttribute
10{
11    public string $message;
12
13    public function __construct(string $message)
14    {
15        $this->message = $message;
16    }
17}
18
19// 上で定義した`MyCustomAttribute`を適用するサンプルクラスです。
20// クラス自体と、その中のメソッドに属性を適用しています。
21#[MyCustomAttribute('これはクラスレベルの属性です')]
22class MySampleClass
23{
24    #[MyCustomAttribute('これはメソッドレベルの属性です')]
25    public function sampleMethod(): void
26    {
27        // このメソッドは属性を持つだけで、具体的な処理はありません
28    }
29
30    public function anotherMethod(): void
31    {
32        // このメソッドには属性がありません
33    }
34}
35
36/**
37 * Attribute::TARGET_* 定数ビットマスクを、システムエンジニア初心者にも分かりやすい文字列に変換するヘルパー関数。
38 *
39 * ReflectionAttribute::getTarget() が返す数値（ビットマスク）を、
40 * 人間が読める形式のターゲット名（例: 'CLASS', 'METHOD'）に変換します。
41 * PHP 8.0で利用可能なターゲット定数のみを考慮しています。
42 *
43 * @param int $target Attributesのターゲットを示すビットマスク値。
44 * @return string ターゲット名の組み合わせをパイプ記号で連結した文字列。
45 */
46function getTargetNames(int $target): string
47{
48    $names = [];
49    if ($target & Attribute::TARGET_CLASS) {
50        $names[] = 'CLASS'; // クラスに適用された属性
51    }
52    if ($target & Attribute::TARGET_FUNCTION) {
53        $names[] = 'FUNCTION'; // 関数に適用された属性
54    }
55    if ($target & Attribute::TARGET_METHOD) {
56        $names[] = 'METHOD'; // メソッドに適用された属性
57    }
58    if ($target & Attribute::TARGET_PROPERTY) {
59        $names[] = 'PROPERTY'; // プロパティに適用された属性
60    }
61    if ($target & Attribute::TARGET_CLASS_CONSTANT) {
62        $names[] = 'CLASS_CONSTANT'; // クラス定数に適用された属性
63    }
64    if ($target & Attribute::TARGET_PARAMETER) {
65        $names[] = 'PARAMETER'; // パラメータに適用された属性
66    }
67    // PHP 8.0 の Attribute 定数には TARGET_FILE は含まれていません (PHP 8.2以降で追加)
68
69    return empty($names) ? 'UNKNOWN (またはターゲットが指定されていない)' : implode(' | ', $names);
70}
71
72/**
73 * ReflectionAttribute::getTarget メソッドの動作をデモンストレーションする関数。
74 *
75 * この関数は、`MySampleClass`およびそのメソッドに適用された属性をリフレクションで取得し、
76 * 各`ReflectionAttribute`オブジェクトの`getTarget()`メソッドを呼び出して、
77 * その属性が実際に適用されている要素のタイプ（ターゲット）を調べて表示します。
78 */
79function demonstrateReflectionAttributeGetTarget(): void
80{
81    echo "--- クラスの属性を分析 ---\n";
82    // `MySampleClass`をリフレクションオブジェクトとして取得します。
83    $classReflector = new ReflectionClass(MySampleClass::class);
84
85    // クラスに直接適用されているすべての属性を取得します。
86    $classAttributes = $classReflector->getAttributes();
87
88    if (empty($classAttributes)) {
89        echo "  MySampleClass にクラスレベルの属性が見つかりませんでした。\n";
90    } else {
91        foreach ($classAttributes as $attribute) {
92            // 私たちが定義した`MyCustomAttribute`のみに関心があるので、その属性のみを処理します。
93            if ($attribute->getName() === MyCustomAttribute::class) {
94                // `getTarget()`メソッドを呼び出し、属性が適用された要素のタイプを示すビットマスクを取得します。
95                // ここでは`ReflectionClass`から属性を取得しているので、
96                // 戻り値は通常`Attribute::TARGET_CLASS`のビットが立った値になります。
97                $targetBitmask = $attribute->getTarget();
98
99                echo "  属性 '" . $attribute->getName() . "' (値: " . $attribute->newInstance()->message . ")\n";
100                echo "    この属性がリフレクションされたオブジェクトのタイプ: ReflectionClass\n";
101                echo "    getTarget() の戻り値: " . $targetBitmask . " (整数値のビットマスク)\n";
102                echo "    解釈されたターゲット: " . getTargetNames($targetBitmask) . "\n";
103            }
104        }
105    }
106
107    echo "\n--- メソッドの属性を分析 ---\n";
108    // `MySampleClass`の`sampleMethod`をリフレクションオブジェクトとして取得します。
109    $methodReflector = $classReflector->getMethod('sampleMethod');
110
111    // メソッドに直接適用されているすべての属性を取得します。
112    $methodAttributes = $methodReflector->getAttributes();
113
114    if (empty($methodAttributes)) {
115        echo "  MySampleClass::sampleMethod にメソッドレベルの属性が見つかりませんでした。\n";
116    } else {
117        foreach ($methodAttributes as $attribute) {
118            // 私たちが定義した`MyCustomAttribute`のみに関心があるので、その属性のみを処理します。
119            if ($attribute->getName() === MyCustomAttribute::class) {
120                // `getTarget()`メソッドを呼び出し、属性が適用された要素のタイプを示すビットマスクを取得します。
121                // ここでは`ReflectionMethod`から属性を取得しているので、
122                // 戻り値は通常`Attribute::TARGET_METHOD`のビットが立った値になります。
123                $targetBitmask = $attribute->getTarget();
124
125                echo "  属性 '" . $attribute->getName() . "' (値: " . $attribute->newInstance()->message . ")\n";
126                echo "    この属性がリフレクションされたオブジェクトのタイプ: ReflectionMethod\n";
127                echo "    getTarget() の戻り値: " . $targetBitmask . " (整数値のビットマスク)\n";
128                echo "    解釈されたターゲット: " . getTargetNames($targetBitmask) . "\n";
129            }
130        }
131    }
132}
133
134// デモンストレーション関数を実行し、結果を表示します。
135demonstrateReflectionAttributeGetTarget();

PHP 8で導入された「属性」（アノテーション）は、クラスやメソッドなどのコード要素にメタデータを付与する機能です。ReflectionAttribute::getTarget()メソッドは、この属性がどの種類のPHP要素に適用されているかを調べる際に利用されます。

このメソッドは引数を一切取りません。戻り値は整数型（int）で、これは属性が適用された要素のタイプを示すビットマスクです。例えば、クラスに適用された属性であればAttribute::TARGET_CLASSに相当する値、メソッドに適用された属性であればAttribute::TARGET_METHODに相当する値が返されます。これにより、その属性がクラスに付与されたものか、メソッドに付与されたものかなどを判別できます。

サンプルコードでは、MyCustomAttributeをクラスとメソッドに適用可能と定義し、MySampleClassのクラス自体とsampleMethodに属性を付与しています。demonstrateReflectionAttributeGetTarget()関数でリフレクションを通じてこれらの属性を取得し、$attribute->getTarget()を呼び出しています。この呼び出しにより、クラスに適用された属性からはクラスを示す値が、メソッドに適用された属性からはメソッドを示す値が返され、属性が実際にどこに付与されたのかを正確に特定できることを示しています。