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

Copy
1<?php
2
3// PHP 8.1以降でEnumがサポートされています。属性はPHP 8.0で導入されました。
4
5/**
6 * AttachableInfoインターフェースを定義します。
7 * これは、属性が特定の情報を提供する型であることを示すマーカーとして機能します。
8 */
9interface AttachableInfo
10{
11    // この例ではメソッドは不要です。型ヒントとして使用されます。
12}
13
14/**
15 * Enumに関する情報を提供するカスタム属性です。
16 * クラスとEnumの両方をターゲットにできます。
17 */
18#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_ENUM)]
19class EnumInfo implements AttachableInfo
20{
21    /**
22     * @param string $description Enumの記述的なテキスト。
23     */
24    public function __construct(public string $description)
25    {
26    }
27}
28
29/**
30 * さまざまなステータスを表すサンプルEnumです。
31 * カスタム属性が適用されています。
32 */
33#[EnumInfo('このEnumはデモンストレーション目的のサンプルステータスEnumです。')]
34enum Status: string
35{
36    case Active = 'active';
37    case Inactive = 'inactive';
38}
39
40// Status EnumのReflectionClassインスタンスを作成します。
41// Enumの場合（PHP 8.1以降）、ReflectionClassはReflectionEnumのインスタンスになります。
42$reflectionClass = new ReflectionClass(Status::class);
43
44// 反映対象がEnumであることを確認します。
45if ($reflectionClass instanceof ReflectionEnum) {
46    echo "--- Enum: " . $reflectionClass->getName() . " のリフレクション ---" . PHP_EOL . PHP_EOL;
47
48    // 1. Enum自体に宣言されているすべての属性を取得します。
49    echo "1. Enumに宣言されているすべての属性を取得:" . PHP_EOL;
50    $allAttributes = $reflectionClass->getAttributes();
51
52    if (empty($allAttributes)) {
53        echo "   Enumに属性が見つかりませんでした。" . PHP_EOL;
54    } else {
55        foreach ($allAttributes as $attribute) {
56            echo "   - 属性名: " . $attribute->getName() . PHP_EOL;
57            $args = $attribute->getArguments();
58            if (!empty($args)) {
59                echo "     引数: " . json_encode($args) . PHP_EOL;
60            }
61        }
62    }
63    echo PHP_EOL;
64
65    // 2. 特定の名前（例: EnumInfo属性）でフィルタリングされた属性を取得します。
66    echo "2. 'EnumInfo'という名前の属性を特定して取得:" . PHP_EOL;
67    $specificAttributes = $reflectionClass->getAttributes(EnumInfo::class);
68
69    if (empty($specificAttributes)) {
70        echo "   Enumに'EnumInfo'という名前の属性は見つかりませんでした。" . PHP_EOL;
71    } else {
72        foreach ($specificAttributes as $attribute) {
73            echo "   - 属性名: " . $attribute->getName() . PHP_EOL;
74            $args = $attribute->getArguments();
75            if (!empty($args)) {
76                echo "     引数: " . json_encode($args) . PHP_EOL;
77            }
78        }
79    }
80    echo PHP_EOL;
81
82    // 3. 特定のクラスのインスタンスである、またはインターフェースを実装する属性を取得します（フラグを使用）。
83    echo "3. 'AttachableInfo'インターフェースを実装する属性を取得 (IS_INSTANCEOFフラグを使用):" . PHP_EOL;
84    // 2番目の引数`flags`には`ReflectionAttribute::IS_INSTANCEOF`を指定でき、
85    // 1番目の引数`name`がクラスまたはインターフェース名である場合に有効です。
86    $filteredByInterface = $reflectionClass->getAttributes(AttachableInfo::class, ReflectionAttribute::IS_INSTANCEOF);
87
88    if (empty($filteredByInterface)) {
89        echo "   'AttachableInfo'インターフェースを実装する属性は見つかりませんでした。" . PHP_EOL;
90    } else {
91        foreach ($filteredByInterface as $attribute) {
92            echo "   - 属性名: " . $attribute->getName() . PHP_EOL;
93            $args = $attribute->getArguments();
94            if (!empty($args)) {
95                echo "     引数: " . json_encode($args) . PHP_EOL;
96            }
97        }
98    }
99    echo PHP_EOL;
100
101} else {
102    echo "エラー: 指定されたクラス '" . Status::class . "' はEnumではありません。" . PHP_EOL;
103}
104

ReflectionEnum::getAttributesメソッドは、Enumに適用された「属性」（Attribute）と呼ばれる追加情報を、プログラムの実行中に取得するために使用されます。属性は、Enum自体に特定のメタデータや設定を付与する際に役立ちます。

このメソッドには二つの引数があります。一つ目の引数$nameは、取得したい属性のクラス名を指定します。この引数を省略すると、そのEnumに定義されているすべての属性が取得されます。特定の属性だけを対象にしたい場合に指定します。二つ目の引数$flagsは、属性の取得方法をさらに細かく制御するためのものです。例えば、ReflectionAttribute::IS_INSTANCEOFフラグを指定すると、一つ目の引数$nameで指定したクラスを継承しているか、インターフェースを実装している属性のみを取得できます。

メソッドの戻り値は、条件に合致した属性の情報を格納するReflectionAttributeオブジェクトの配列です。このオブジェクトを通じて、属性の名前やコンストラクタの引数などを調べることができます。

サンプルコードでは、StatusというEnumに定義されたカスタム属性EnumInfoを例に、引数なしで全ての属性を取得する方法、特定の属性名でフィルタリングする方法、そして特定のインターフェースを実装する属性をIS_INSTANCEOFフラグを使って取得する方法が具体的に示されており、動的にEnumの情報を取得する強力な手段であることが理解できます。

Copy
1<?php
2
3/**
4 * カスタム属性を定義します。
5 * この属性はクラス（Enumも含む）に適用できます。
6 */
7#[Attribute(Attribute::TARGET_CLASS)]
8class EnumInfo
9{
10    public function __construct(
11        public string $description,
12        public int $version = 1
13    ) {}
14}
15
16/**
17 * 属性が適用された列挙型（Enum）を定義します。
18 * PHP 8.1以降で利用可能です。
19 */
20#[EnumInfo('アプリケーションの状態を表す列挙型です。', version: 2)]
21enum Status
22{
23    case PENDING;
24    case APPROVED;
25    case REJECTED;
26}
27
28/**
29 * ReflectionEnum::getAttributes() の使用例を示します。
30 * 列挙型自体に適用された属性を取得し、その情報を表示します。
31 */
32function demonstrateReflectionEnumAttributes(): void
33{
34    // リフレクション対象のEnumクラス名を指定します。
35    $enumClassName = Status::class;
36
37    try {
38        // ReflectionEnumのインスタンスを作成します。
39        // これにより、Enumの構造に関する情報を取得できるようになります。
40        $reflectionEnum = new ReflectionEnum($enumClassName);
41
42        echo "Enum '" . $reflectionEnum->getName() . "' の属性情報:\n";
43
44        // Enumクラス自体に適用された属性のリストを取得します。
45        // getAttributes()はReflectionAttributeオブジェクトの配列を返します。
46        // 引数を指定しない場合、すべての属性を取得します。
47        $attributes = $reflectionEnum->getAttributes();
48
49        if (empty($attributes)) {
50            echo "  このEnumには属性が見つかりませんでした。\n";
51            return;
52        }
53
54        foreach ($attributes as $attribute) {
55            echo "  - 属性名: " . $attribute->getName() . "\n";
56
57            // 属性のインスタンスを作成し、その引数（コンストラクタパラメータ）にアクセスします。
58            // 例えば #[EnumInfo('説明', version: 2)] の '説明' や '2' を取得できます。
59            $attributeInstance = $attribute->newInstance();
60
61            if ($attributeInstance instanceof EnumInfo) {
62                echo "    説明: " . $attributeInstance->description . "\n";
63                echo "    バージョン: " . $attributeInstance->version . "\n";
64            } else {
65                // 他のカスタム属性がある場合も考慮できます
66                echo "    属性のインスタンスが作成されました。\n";
67            }
68        }
69    } catch (ReflectionException $e) {
70        echo "リフレクションエラー: " . $e->getMessage() . "\n";
71    }
72}
73
74// 関数を実行して、結果を出力します。
75demonstrateReflectionEnumAttributes();
76
77?>

ReflectionEnum::getAttributes() メソッドは、PHPのEnum（列挙型）の定義に付加された「属性」（メタ情報）を動的に取得する際に使用されます。リフレクション機能は、プログラムの実行中にコードの構造を調べたり操作したりすることを可能にします。

このメソッドは、ReflectionEnum クラスのインスタンスに対して呼び出され、特定のEnumに適用されているカスタム属性や標準属性の情報を取得します。引数に属性名を指定すると、その名前の属性のみをフィルタリングして取得できますが、指定しない場合はすべての属性が取得されます。また、属性の検索方法を制御するオプションを指定できます。戻り値としては、取得された属性の情報を表す ReflectionAttribute オブジェクトの配列が返されます。

サンプルコードでは、EnumInfo というカスタム属性を定義し、Status Enumに適用しています。ReflectionEnum のインスタンスを通じて getAttributes() を呼び出すことで、Status Enumに付加された EnumInfo 属性が取得されます。その後、各 ReflectionAttribute オブジェクトから newInstance() メソッドを使って属性の実際のインスタンスを生成し、属性に設定された description や version といった値にアクセスして表示しています。これにより、Enumの定義に付加されたメタデータをプログラムから利用できるようになります。