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

Copy
1<?php
2
3// PHP 8以降で利用可能なカスタム属性を定義します。
4// Enumケースに属性を付与する場合、Attribute::TARGET_CLASS_CONSTANT が必要です。
5#[Attribute(Attribute::TARGET_CLASS_CONSTANT)]
6class CustomTag
7{
8    /**
9     * @param string $description この属性の説明
10     * @param array<string> $tags 関連するタグの配列
11     */
12    public function __construct(
13        public string $description,
14        public array $tags = []
15    ) {}
16}
17
18// PHP 8.1以降で利用可能な列挙型（Enum）を定義します。
19enum TaskStatus
20{
21    // 各Enumケースに CustomTag 属性を付与します。
22    #[CustomTag('タスクはまだ開始されていません。', ['todo', 'new'])]
23    case Pending;
24
25    #[CustomTag('タスクは現在進行中です。', ['doing', 'in-progress'])]
26    case InProgress;
27
28    #[CustomTag('タスクは完了しました。', ['done', 'completed'])]
29    case Completed;
30}
31
32/**
33 * 指定されたEnumケースに付与された属性を取得し、その情報を表示する関数です。
34 *
35 * @param string $enumClassName Enumの完全修飾クラス名（例: TaskStatus::class）
36 * @param string $caseName      属性を取得したいEnumケースの名前（例: 'Pending'）
37 */
38function displayEnumCaseAttributes(string $enumClassName, string $caseName): void
39{
40    echo "--- Enum: {$enumClassName}, Case: {$caseName} の属性情報 ---\n";
41
42    try {
43        // ReflectionEnum を使って、Enumクラス全体のリフレクションオブジェクトを作成します。
44        $reflectionEnum = new ReflectionEnum($enumClassName);
45
46        // getCase メソッドを使って、特定のEnumケース（例: TaskStatus::Pending）の
47        // ReflectionEnumUnitCase オブジェクトを取得します。
48        $reflectionCase = $reflectionEnum->getCase($caseName);
49
50        // ReflectionEnumUnitCase::getAttributes メソッドを呼び出して、
51        // このEnumケースに付与されているすべての属性（Attribute）のリストを取得します。
52        // 引数として属性名（文字列）を指定することで、特定の属性のみをフィルタリングすることも可能です。
53        // 例: $reflectionCase->getAttributes(CustomTag::class);
54        $attributes = $reflectionCase->getAttributes();
55
56        if (empty($attributes)) {
57            echo "  このEnumケースには属性が定義されていません。\n";
58            return;
59        }
60
61        foreach ($attributes as $attribute) {
62            // 属性のクラス名を取得します。
63            echo "  属性名: " . $attribute->getName() . "\n";
64
65            // 属性のインスタンスを作成します。これにより、属性のコンストラクタで定義された値にアクセスできます。
66            $instance = $attribute->newInstance();
67
68            // インスタンスが CustomTag であるか確認し、そのプロパティを表示します。
69            if ($instance instanceof CustomTag) {
70                echo "    説明: " . $instance->description . "\n";
71                echo "    タグ: " . implode(', ', $instance->tags) . "\n";
72            }
73        }
74    } catch (ReflectionException $e) {
75        // リフレクション処理中にエラーが発生した場合（例: 存在しないEnumクラス名やケース名）
76        echo "  エラーが発生しました: " . $e->getMessage() . "\n";
77    }
78    echo "-------------------------------------------------------\n\n";
79}
80
81// 上で定義した関数を呼び出し、Enumケースの属性情報を表示します。
82displayEnumCaseAttributes(TaskStatus::class, 'Pending');
83displayEnumCaseAttributes(TaskStatus::class, 'InProgress');
84displayEnumCaseAttributes(TaskStatus::class, 'Completed');
85
86// 存在しないEnumケース名を指定した場合の例
87displayEnumCaseAttributes(TaskStatus::class, 'NonExistent');
88
89?>

PHPのReflectionEnumUnitCase::getAttributesメソッドは、リフレクション機能を用いて、Enum（列挙型）の特定のケースに付与されたカスタム属性の情報を取得する役割を持ちます。このメソッドは、引数$nameで属性のクラス名を指定することで、特定の種類の属性のみをフィルタリングでき、見つかった属性をReflectionAttributeオブジェクトの配列として戻り値のarrayで返します。

このサンプルコードでは、まずCustomTagというカスタム属性を定義し、Enumの各ケース（Pending、InProgress、Completed）に、タスクの状態に関する詳細情報として付与しています。displayEnumCaseAttributes関数は、指定されたEnumクラス名とケース名から、ReflectionEnumとgetCaseを使って該当するReflectionEnumUnitCaseオブジェクトを取得します。次に、そのオブジェクトのgetAttributesメソッドを呼び出すことで、Enumケースに設定されたCustomTag属性のリストを得ています。

取得したReflectionAttributeオブジェクトからは、newInstance()メソッドを使って属性のインスタンスを作成し、そのインスタンスに定義されたdescriptionやtagsといった具体的な値にアクセスし、表示しています。これにより、Enumケースの定義に直接埋め込まれた追加のメタデータ（付加情報）を、プログラム実行中に動的に読み取り、活用することが可能になります。

Copy
1<?php
2
3// このサンプルコードは、PHP 8.1以降で導入されたEnum（列挙型）のケースに付与されたアトリビュート
4// （属性）をリフレクション（プログラム実行中にその構造を調べること）する方法を示します。
5// ReflectionEnumUnitCase クラスは、バッキング値（例: stringやintの関連付け）を持たない
6// Enumケース（例: enum Status { case Active; } の 'Active'）を扱うために使用されます。
7
8// 1. Enumケースに付与するためのカスタムアトリビュートを定義します。
9// `#[Attribute(Attribute::TARGET_ENUM_CASE)]` を指定することで、このアトリビュートが
10// Enumケースにのみ適用可能であることを示します。
11#[Attribute(Attribute::TARGET_ENUM_CASE)]
12class CaseDescription
13{
14    // コンストラクタでアトリビュートの値を定義します。
15    public function __construct(public string $description) {}
16}
17
18// 2. カスタムアトリビュートを持つEnumを定義します。
19enum Status
20{
21    // 'Active' ケースに CaseDescription アトリビュートを付与します。
22    #[CaseDescription("ユーザーが現在活動中であることを示します。")]
23    case Active;
24
25    // 'Inactive' ケースにも CaseDescription アトリビュートを付与します。
26    #[CaseDescription("ユーザーが現在活動していないことを示します。")]
27    case Inactive;
28
29    // 'Pending' ケースはアトリビュートを持ちません。
30    case Pending;
31}
32
33// 3. ReflectionEnumUnitCase を使って Enum ケースのアトリビュートを取得し、表示します。
34
35// まず、Enumクラス自体をリフレクションします。
36$reflectionEnum = new ReflectionEnum(Status::class);
37
38// --- 'Active' ケースのアトリビュート情報を取得する例 ---
39
40// 'Active' ケースの ReflectionEnumUnitCase インスタンスを取得します。
41$reflectionCaseActive = $reflectionEnum->getCase('Active');
42
43echo "--- Enumケース 'Active' のアトリビュート情報 ---\n";
44
45// ReflectionEnumUnitCase::getAttributes() メソッドを呼び出し、
46// 'Active' ケースに付与されたすべてのアトリビュート（ReflectionAttributeオブジェクトの配列）を取得します。
47$attributesForActive = $reflectionCaseActive->getAttributes();
48
49if (empty($attributesForActive)) {
50    echo "アトリビュートは見つかりませんでした。\n";
51} else {
52    foreach ($attributesForActive as $attribute) {
53        // 取得したアトリビュートのクラス名（完全修飾名）を取得します。
54        echo "  アトリビュート名: " . $attribute->getName() . "\n";
55
56        // アトリビュートのインスタンスを生成し、そのコンストラクタ引数にアクセスします。
57        $instance = $attribute->newInstance();
58        if ($instance instanceof CaseDescription) {
59            echo "    説明: " . $instance->description . "\n";
60        }
61    }
62}
63echo "\n";
64
65// --- 'Pending' ケース（アトリビュートを持たないケース）のアトリビュート情報を取得する例 ---
66
67// 'Pending' ケースの ReflectionEnumUnitCase インスタンスを取得します。
68$reflectionCasePending = $reflectionEnum->getCase('Pending');
69$attributesForPending = $reflectionCasePending->getAttributes();
70
71echo "--- Enumケース 'Pending' のアトリビュート情報 ---\n";
72if (empty($attributesForPending)) {
73    echo "  アトリビュートは見つかりませんでした。\n";
74} else {
75    foreach ($attributesForPending as $attribute) {
76        echo "  アトリビュート名: " . $attribute->getName() . "\n";
77        $instance = $attribute->newInstance();
78        if ($instance instanceof CaseDescription) {
79            echo "    説明: " . $instance->description . "\n";
80        }
81    }
82}
83echo "\n";
84
85// --- 特定のアトリビュート名でフィルタリングする例（'Active' ケース） ---
86// getAttributes() メソッドの第一引数にアトリビュートのクラス名を指定することで、
87// 特定のアトリビュートのみをフィルタリングして取得できます。
88
89echo "--- 特定のアトリビュート名でフィルタリング（'Active' ケース）---\n";
90$filteredAttributes = $reflectionCaseActive->getAttributes(CaseDescription::class);
91
92if (empty($filteredAttributes)) {
93    echo "  指定されたアトリビュートは見つかりませんでした。\n";
94} else {
95    foreach ($filteredAttributes as $attribute) {
96        echo "  フィルタリングされたアトリビュート名: " . $attribute->getName() . "\n";
97        $instance = $attribute->newInstance();
98        if ($instance instanceof CaseDescription) {
99            echo "    説明: " . $instance->description . "\n";
100        }
101    }
102}
103
104?>

このコードは、PHP 8.1以降で導入されたEnum（列挙型）の特定のケースに付与されたアトリビュート（属性）を、リフレクション（プログラム実行中にその構造を調べる機能）を使って取得する方法を解説しています。特にReflectionEnumUnitCaseクラスは、整数や文字列のようなバッキング値を持たないEnumケース（例：enum Status { case Active; }のActive）のアトリビュートを扱います。

サンプルコードでは、まずEnumケースにメタデータとして追加するカスタムアトリビュートCaseDescriptionを定義しています。次に、StatusというEnumを定義し、ActiveやInactiveといったケースにCaseDescriptionアトリビュートを適用しています。

ReflectionEnumUnitCase::getAttributes()メソッドは、対象のEnumケースに付与されたすべてのアトリビュートをReflectionAttributeオブジェクトの配列として返します。第一引数$nameにアトリビュートの完全修飾クラス名（例: CaseDescription::class）を指定すると、特定の種類のアトリビュートのみをフィルタリングして取得できます。第二引数$flagsは検索動作を調整するためのものですが、ここではデフォルト値を使用しています。取得したReflectionAttributeオブジェクトからは、アトリビュートのクラス名や、newInstance()メソッドを使ってそのアトリビュートのインスタンスを生成し、設定された値にアクセスすることが可能です。これにより、Enumケースに付与された追加情報をプログラム実行時に動的に読み取り、活用できるようになります。