【PHP8.x】ReflectionAttribute::nameプロパティの使い方

Copy
1<?php
2
3// PHPのカスタム属性（Attribute）を定義するための名前空間です。
4// この `CustomAttribute` クラスは `App\Attributes` 名前空間に属します。
5namespace App\Attributes;
6
7use Attribute; // PHP 8から導入されたAttributeインターフェースをインポートします。
8
9/**
10 * システムの振る舞いを記述するためのカスタム属性の例です。
11 * `#[Attribute(...)]` は、このクラスがPHPの属性として使用できることを示します。
12 * `Attribute::TARGET_CLASS` はクラスに、`Attribute::TARGET_METHOD` はメソッドにこの属性を適用できることを意味します。
13 */
14#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD)]
15class CustomAttribute
16{
17    /**
18     * 属性が使用される際に渡される値を保持するためのコンストラクタです。
19     *
20     * @param string $value この属性に関連付けられる任意の文字列値
21     */
22    public function __construct(public string $value) {}
23}
24
25// 属性を適用するクラスや関数を定義するための別の名前空間です。
26// この `MyService` クラスは `App\Services` 名前空間に属します。
27namespace App\Services;
28
29// `App\Attributes` 名前空間で定義された `CustomAttribute` をインポートします。
30// これにより、`#[CustomAttribute(...)]` という簡潔な形式で属性を使用できるようになります。
31use App\Attributes\CustomAttribute;
32
33/**
34 * カスタム属性が適用されたサンプルサービスです。
35 * クラスやメソッドに属性を適用することで、メタデータ（付加情報）を追加できます。
36 */
37#[CustomAttribute('この属性はMyServiceクラス全体に適用されています。')]
38class MyService
39{
40    /**
41     * カスタム属性が適用されたメソッドの例です。
42     */
43    #[CustomAttribute('この属性はperformActionメソッドに適用されています。')]
44    public function performAction(): string
45    {
46        return "アクションが実行されました。";
47    }
48}
49
50/**
51 * リフレクションAPIを使用して、定義した属性の名前（名前空間を含む）を取得する関数です。
52 * `ReflectionAttribute::name` プロパティの動作を、名前空間のコンテキストで示します。
53 * システムエンジニアを目指す初心者の方にも、PHPの名前空間とリフレクションの基本的な関連性を理解しやすくすることを目的としています。
54 */
55function demonstrateReflectionAttributeName(): void
56{
57    echo "--- 'App\\Services\\MyService' クラスのリフレクション ---\n";
58
59    // 'App\Services\MyService' クラスのリフレクションオブジェクトを作成します。
60    // \ReflectionClass のようにバックスラッシュを先頭に付けることで、
61    // 現在の名前空間 (App\Services) に影響されずにグローバルなクラスを参照できます。
62    $reflector = new \ReflectionClass(\App\Services\MyService::class);
63
64    // クラスに適用されているすべての属性を取得します。
65    // `getAttributes()` メソッドは `ReflectionAttribute` オブジェクトの配列を返します。
66    $classAttributes = $reflector->getAttributes();
67    foreach ($classAttributes as $attribute) {
68        // `ReflectionAttribute::name` プロパティは、属性の完全修飾名（FQCN - Fully Qualified Class Name）を文字列で返します。
69        // ここには、属性が定義されている名前空間 (`App\Attributes`) も含まれています。
70        echo "クラス属性の完全修飾名 (FQCN): " . $attribute->name . "\n";
71    }
72
73    echo "\n--- 'App\\Services\\MyService::performAction' メソッドのリフレクション ---\n";
74
75    // 'performAction' メソッドのリフレクションオブジェクトを取得します。
76    $methodReflector = $reflector->getMethod('performAction');
77
78    // メソッドに適用されているすべての属性を取得します。
79    $methodAttributes = $methodReflector->getAttributes();
80    foreach ($methodAttributes as $attribute) {
81        // メソッド属性の完全修飾名（FQCN）を取得します。
82        echo "メソッド属性の完全修飾名 (FQCN): " . $attribute->name . "\n";
83    }
84}
85
86// 上記の関数を実行し、結果を出力します。
87demonstrateReflectionAttributeName();
88
89?>

PHP 8で導入された「属性（Attribute）」は、クラスやメソッド、プロパティなどに「付加情報（メタデータ）」を与える機能です。ReflectionAttributeクラスは、プログラム実行中にこれらの属性情報を動的に取得・操作する際に使用されます。

ReflectionAttributeクラスのnameプロパティは、その属性の完全なクラス名を文字列として取得します。このプロパティには引数はなく、戻り値は常にstring型です。PHPの名前空間（namespace）を使用している場合、このnameプロパティは属性が定義されている名前空間の情報を含む「完全修飾名（FQCN - Fully Qualified Class Name）」を返します。

サンプルコードでは、App\Attributes名前空間でCustomAttributeという独自の属性を定義し、それをApp\Services名前空間にあるMyServiceクラスとそのperformActionメソッドに適用しています。その後、ReflectionClassやReflectionMethodを使ってこれらの属性情報を取得し、$attribute->nameで出力すると、「App\Attributes\CustomAttribute」のように、名前空間を含む正確な属性名が表示されます。これにより、どの名前空間で定義された属性が適用されているかをプログラムから正確に識別できます。

Copy
1<?php
2
3declare(strict_types=1);
4
5namespace App\Attributes; // アトリビュート定義用の名前空間
6
7use Attribute;
8
9/**
10 * カスタムアトリビュートの定義。
11 * このアトリビュートは `App\Attributes` 名前空間に属しており、
12 * これはPHPの命名規則に沿ったものです。
13 *
14 * `Attribute::TARGET_CLASS` はクラスに、`Attribute::TARGET_METHOD` はメソッドに
15 * このアトリビュートを付与できることを示します。
16 */
17#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD)]
18class MetadataExample
19{
20    public string $description;
21
22    public function __construct(string $description)
23    {
24        $this->description = $description;
25    }
26}
27
28namespace App\Services; // 実際のサービスコード用の名前空間
29
30use App\Attributes\MetadataExample; // 定義したアトリビュートをuseする
31
32/**
33 * MyServiceクラスは、`MetadataExample` アトリビュートを使用してメタデータを付与されます。
34 * このクラスは `App\Services` 名前空間に属しており、これも命名規則に沿っています。
35 *
36 * アトリビュートを適用する際、`use` ステートメントにより短縮名 (`MetadataExample`) で記述しますが、
37 * 内部的には完全修飾名 (FQN: Fully Qualified Name) が使用されます。
38 */
39#[MetadataExample("このサービスは顧客データを管理します")]
40class CustomerService
41{
42    /**
43     * getCustomerByIdメソッドも`MetadataExample`アトリビュートを持ちます。
44     * ここでも短縮名を使用していますが、リフレクション時にはFQNが取得されます。
45     */
46    #[MetadataExample("特定の顧客IDで顧客情報を取得します")]
47    public function getCustomerById(int $id): array
48    {
49        // 実際の顧客取得ロジック
50        return ['id' => $id, 'name' => 'John Doe'];
51    }
52
53    /**
54     * updateCustomerメソッドにはアトリビュートが付与されていません。
55     */
56    public function updateCustomer(int $id, array $data): bool
57    {
58        // 実際の顧客更新ロジック
59        return true;
60    }
61}
62
63/**
64 * 指定されたクラスからアトリビュート情報を抽出し、
65 * その完全修飾名 (FQN) を表示する関数。
66 * システムエンジニアを目指す初心者の方へ、
67 * `ReflectionAttribute::name` プロパティがどのようにアトリビュートの名前空間と
68 * クラス名を含む完全な名前を返すかを示します。
69 */
70function extractAndDisplayAttributeNames(): void
71{
72    // CustomerServiceクラスのReflectionインスタンスを作成
73    // PHP 8では名前空間付きのクラスは完全修飾名で指定する必要があります。
74    $reflectionClass = new \ReflectionClass(\App\Services\CustomerService::class);
75
76    echo "--- クラスのアトリビュート情報 ---\n";
77    // クラスに付与された全てのアトリビュートを取得
78    $classAttributes = $reflectionClass->getAttributes();
79    if (empty($classAttributes)) {
80        echo "  クラスにアトリビュートは見つかりませんでした。\n";
81    } else {
82        foreach ($classAttributes as $attribute) {
83            // ReflectionAttribute::name プロパティは、アトリビュートの完全修飾名 (FQN) を返します。
84            // ここでは、定義時に使用した名前空間 (`App\Attributes`) が含まれます。
85            echo "  アトリビュートの完全名 (FQN): " . $attribute->name . "\n";
86
87            // アトリビュートのインスタンスを生成し、そのプロパティにアクセスすることも可能です。
88            $instance = $attribute->newInstance();
89            echo "  アトリビュートのdescription: " . $instance->description . "\n";
90        }
91    }
92
93    echo "\n--- メソッドのアトリビュート情報 ---\n";
94    // getCustomerByIdメソッドのReflectionインスタンスを取得
95    $reflectionMethod = $reflectionClass->getMethod('getCustomerById');
96    // メソッドに付与された全てのアトリビュートを取得
97    $methodAttributes = $reflectionMethod->getAttributes();
98    if (empty($methodAttributes)) {
99        echo "  メソッドにアトリビュートは見つかりませんでした。\n";
100    } else {
101        foreach ($methodAttributes as $attribute) {
102            echo "  アトリビュートの完全名 (FQN): " . $attribute->name . "\n";
103            $instance = $attribute->newInstance();
104            echo "  アトリビュートのdescription: " . $instance->description . "\n";
105        }
106    }
107
108    echo "\n--- アトリビュートのないメソッドの確認 ---\n";
109    // updateCustomerメソッドはアトリビュートが付与されていないことを確認
110    $reflectionMethodNoAttr = $reflectionClass->getMethod('updateCustomer');
111    $noAttributes = $reflectionMethodNoAttr->getAttributes();
112    if (empty($noAttributes)) {
113        echo "  'updateCustomer' メソッドにはアトリビュートが見つかりませんでした。期待通りです。\n";
114    } else {
115        echo "  'updateCustomer' メソッドに予期せずアトリビュートが見つかりました。\n";
116    }
117}
118
119// アトリビュート情報の抽出と表示を実行
120extractAndDisplayAttributeNames();

PHP 8から導入されたアトリビュートは、クラスやメソッドなどに付加情報（メタデータ）を宣言的に付与できる機能です。ReflectionAttribute::nameプロパティは、リフレクションを通じて取得したアトリビュートの「完全修飾名（FQN）」を知るために使用されます。このプロパティは引数を受け取らず、アトリビュートの完全修飾名を文字列として返します。

完全修飾名とは、PHPの命名規則に基づき、アトリビュートが定義された名前空間（例：App\Attributes）とクラス名（例：MetadataExample）を組み合わせた、一意の名前のことです。

サンプルコードでは、CustomerServiceクラスやメソッドに付与されたMetadataExampleアトリビュートの完全修飾名が、$attribute->nameを通じてApp\Attributes\MetadataExampleとして取得・表示されることを確認できます。ReflectionAttribute::nameは、実行時にアトリビュートの正確な名前を識別し、それに応じた処理を行う際に役立ちます。