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

Copy
1<?php
2
3// #[Attribute] 属性クラスの定義
4// この属性は、後述のEnumのケース（定数）に付与されます。
5// Attribute::TARGET_CLASS_CONSTANT は、この属性がEnumケースを含むクラス定数に適用可能であることを示します。
6#[Attribute(Attribute::TARGET_CLASS_CONSTANT)]
7class StatusDescription
8{
9    // コンストラクタで属性の値を設定します。
10    public function __construct(public string $text) {}
11}
12
13// PHP 8.1 で導入されたバックアップEnumの定義
14// string型の値をバックアップとして持ちます。
15enum UserStatus: string
16{
17    // EnumのケースにStatusDescription属性を付与します。
18    // このケースはバックアップ値 'active' を持ちます。
19    #[StatusDescription('ユーザーは現在アクティブな状態です。')]
20    case ACTIVE = 'active';
21
22    // 別のEnumケースにも属性を付与します。
23    // このケースはバックアップ値 'pending' を持ちます。
24    #[StatusDescription('ユーザーは操作を待っている状態です。')]
25    case PENDING = 'pending';
26
27    // 属性が付与されていないEnumケースです。
28    // このケースはバックアップ値 'deleted' を持ちます。
29    case DELETED = 'deleted';
30}
31
32/**
33 * ReflectionEnumBackedCase::getAttributes() の使用例を示します。
34 * この関数は、Enumのバックアップケースに付与された属性情報を取得し、表示します。
35 *
36 * この機能は PHP 8.1 以降で利用可能です。
37 */
38function demonstrateReflectionEnumBackedCaseAttributes(): void
39{
40    echo "--- Enum バックアップケースの属性情報の取得 ---\n\n";
41
42    // ReflectionEnum を使用して UserStatus Enum 全体のリフレクション情報を取得します。
43    $reflectionEnum = new ReflectionEnum(UserStatus::class);
44
45    // Enum内の全てのケース（ACTIVE, PENDING, DELETED）を取得します。
46    foreach ($reflectionEnum->getCases() as $case) {
47        // getCases() は ReflectionEnumUnitCase または ReflectionEnumBackedCase を返します。
48        // 今回のEnumはバックアップEnumなので、全てのケースが ReflectionEnumBackedCase のインスタンスです。
49        if ($case instanceof ReflectionEnumBackedCase) {
50            echo "■ ケース名: " . $case->getName() . "\n";
51            echo "  バックアップ値: " . $case->getValue() . "\n";
52
53            // getAttributes() メソッドを呼び出して、このケースに付与された全ての属性を取得します。
54            // このメソッドは ReflectionAttribute オブジェクトの配列を返します。
55            $attributes = $case->getAttributes();
56
57            if (empty($attributes)) {
58                echo "  このケースには属性がありません。\n";
59            } else {
60                echo "  付与されている属性:\n";
61                foreach ($attributes as $attribute) {
62                    echo "  - 属性名: " . $attribute->getName() . "\n";
63
64                    // ReflectionAttribute::newInstance() を使って属性クラス（StatusDescription）のインスタンスを生成し、
65                    // 属性に渡された引数（コンストラクタの $text）を取得します。
66                    $attributeInstance = $attribute->newInstance();
67                    if ($attributeInstance instanceof StatusDescription) {
68                        echo "    属性のテキスト: " . $attributeInstance->text . "\n";
69                    }
70                }
71            }
72            echo "\n";
73        }
74    }
75}
76
77// 上記のデモンストレーション関数を実行します。
78demonstrateReflectionEnumBackedCaseAttributes();

ReflectionEnumBackedCase::getAttributes()は、PHP 8.1以降で導入されたEnum（列挙型）のバックアップケースに付与されたカスタム属性（Attribute）の情報を取得するメソッドです。

サンプルコードでは、まず#[Attribute]を使ってStatusDescriptionという属性クラスを定義しています。この属性は、Enumのケースに追加情報（テキスト）を付与するために使われます。次に定義されたUserStatus Enumでは、ACTIVEやPENDINGといった各ケースに#[StatusDescription('説明文')]のようにこの属性を付与しています。

ReflectionEnumBackedCase::getAttributes()メソッドは、リフレクションAPIを通じて特定のEnumバックアップケース（例: UserStatus::ACTIVE）にアクセスし、そこに付与された全ての属性をReflectionAttributeオブジェクトの配列として返します。引数に$nameを指定すると、特定の名前の属性のみをフィルタリングして取得できます。取得したReflectionAttributeオブジェクトからは、newInstance()メソッドを通じて属性クラスのインスタンスを生成し、属性が持つ具体的な値（この例ではStatusDescriptionの$textプロパティ）を取り出すことが可能です。これにより、Enumケースに紐付けられたメタデータをプログラムで動的に利用できるようになります。

Copy
1<?php
2
3// 1. カスタム属性を定義
4// ReflectionEnumBackedCase::getAttributes が取得する対象となるカスタム属性です。
5// Attribute::TARGET_ENUM_CASE を指定することで、この属性はEnumのケースにのみ付与できるようになります。
6#[Attribute(Attribute::TARGET_ENUM_CASE)]
7class CaseDetail
8{
9    public function __construct(
10        public string $description,
11        public int $statusCode = 0
12    ) {}
13}
14
15// 2. Backed Enumを定義し、そのケースに属性を付与
16// PHP 8.1以降で導入されたBacked Enumの例です。
17// Enumケース 'Active' と 'Inactive' に上記で定義した CaseDetail 属性を付与しています。
18enum UserStatus: string
19{
20    #[CaseDetail(description: 'ユーザーは現在アクティブな状態です', statusCode: 1)]
21    case Active = 'active';
22
23    #[CaseDetail(description: 'ユーザーは現在非アクティブな状態です')]
24    case Inactive = 'inactive';
25
26    case Pending = 'pending'; // このケースには属性を付与していません
27}
28
29// 3. ReflectionEnumBackedCase::getAttributes の使用例
30// この関数は、指定されたEnumケースに付与された属性情報を取得し、その内容を表示します。
31function demonstrateEnumCaseAttributes(): void
32{
33    echo "--- UserStatus::Active ケースの属性情報 ---" . PHP_EOL;
34
35    // UserStatus EnumクラスのReflectionオブジェクトを作成します。
36    $reflectionEnum = new ReflectionEnum(UserStatus::class);
37
38    // 'Active' という名前のEnumケースのReflectionオブジェクトを取得します。
39    // UserStatusはBacked Enumなので、ReflectionEnumBackedCaseのインスタンスが返されます。
40    $activeCase = $reflectionEnum->getCase('Active');
41
42    // ReflectionEnumBackedCase の getAttributes() メソッドを使用して、
43    // このケースに付与されているすべての属性を取得します。
44    // 引数を指定しない場合、すべての属性がReflectionAttributeオブジェクトの配列として返されます。
45    $attributes = $activeCase->getAttributes();
46
47    if (empty($attributes)) {
48        echo "  UserStatus::Active には属性が見つかりませんでした。" . PHP_EOL;
49    } else {
50        echo "  見つかった属性数: " . count($attributes) . PHP_EOL;
51        foreach ($attributes as $attribute) {
52            echo "  属性名: " . $attribute->getName() . PHP_EOL;
53
54            // 属性のインスタンスを作成し、そのパブリックプロパティにアクセスします。
55            $attributeInstance = $attribute->newInstance();
56            if ($attributeInstance instanceof CaseDetail) {
57                echo "    - 説明: " . $attributeInstance->description . PHP_EOL;
58                echo "    - ステータスコード: " . $attributeInstance->statusCode . PHP_EOL;
59            }
60        }
61    }
62
63    echo PHP_EOL;
64
65    echo "--- UserStatus::Pending ケースの属性情報 (属性なしの例) ---" . PHP_EOL;
66    // 'Pending' ケースには属性が定義されていないため、getAttributes() は空の配列を返します。
67    $pendingCase = $reflectionEnum->getCase('Pending');
68    $pendingAttributes = $pendingCase->getAttributes();
69
70    if (empty($pendingAttributes)) {
71        echo "  UserStatus::Pending には属性が見つかりませんでした。" . PHP_EOL;
72    } else {
73        echo "  見つかった属性数: " . count($pendingAttributes) . PHP_EOL;
74        // 属性が存在する場合のみ、その情報を表示します。
75        foreach ($pendingAttributes as $attribute) {
76            echo "  属性名: " . $attribute->getName() . PHP_EOL;
77        }
78    }
79}
80
81// 関数を実行して、サンプルコードの動作を確認します。
82demonstrateEnumCaseAttributes();

ReflectionEnumBackedCase::getAttributesは、PHP 8.1以降で導入されたEnum（列挙型）の特定のケースに付与されたカスタム属性の情報を取得するためのメソッドです。このメソッドはReflectionEnumBackedCaseクラスに属し、アプリケーションがEnumケースのメタデータにプログラムからアクセスすることを可能にします。

引数には、取得したい属性の名前を文字列で指定でき、特定の属性のみをフィルタリングして取得できます。また、$flags引数を使用すると、属性の取得方法に追加の条件を指定することが可能です。これらの引数を省略した場合、そのEnumケースに付与されているすべてのカスタム属性が対象となります。戻り値は、取得されたReflectionAttributeオブジェクトの配列です。各ReflectionAttributeオブジェクトは、属性の名前や引数など、その属性に関する詳細な情報を提供します。

サンプルコードでは、UserStatusというBacked EnumのActiveケースにCaseDetailというカスタム属性を定義し、getAttributes()メソッドがその属性情報、例えばdescriptionやstatusCodeといった値をどのように取得するかを示しています。属性が定義されていないPendingケースの場合、getAttributes()は空の配列を返し、属性が存在しないことを明確に示します。これにより、Enumケースに付与された追加情報を動的に読み取り、アプリケーションの振る舞いを柔軟に制御できるようになります。