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

Copy
1<?php
2
3/**
4 * PHP 8.1以降で導入されたUnit Enum（値を持たない列挙型）を定義します。
5 * `UnitEnum` インターフェースを明示的に指定する必要はありませんが、
6 * 説明のために記述しています。`enum Status` だけでUnit Enumとなります。
7 */
8enum Status
9{
10    case PENDING;
11    case ACTIVE;
12    case COMPLETED;
13}
14
15/**
16 * Unit Enumのケースからリフレクションを使って値を取得するサンプルコードです。
17 *
18 * ReflectionEnumUnitCase::getValue は、Unit Enumのケースのリフレクションオブジェクトから、
19 * そのEnumケース自体のインスタンスを返します。
20 *
21 * 注意点:
22 * ReflectionEnumUnitCase はPHP内部クラスであり、直接インスタンス化することはできません。
23 * ReflectionEnum::getCase() や ReflectionEnum::getCases() が返す ReflectionEnumCase
24 * オブジェクトがUnit Enumのケースを指している場合、その振る舞いは ReflectionEnumUnitCase と同等です。
25 * そのため、以下のサンプルでは ReflectionEnumCase オブジェクトの getValue() メソッドを使用しています。
26 */
27function demonstrateReflectionEnumUnitCaseGetValue(): void
28{
29    // 1. リフレクションの対象となるEnumケースのインスタンス
30    $originalStatus = Status::ACTIVE;
31    echo "元のEnumケースインスタンス名: " . $originalStatus->name . "\n\n";
32
33    // 2. Enum全体のReflectionオブジェクトを作成
34    $reflectionEnum = new ReflectionEnum(Status::class);
35
36    // 3. 特定のEnumケースのReflectionオブジェクトを取得
37    // getCase() は ReflectionEnumCase のインスタンスを返します。
38    // この場合、Unit Enumのケースなので、実質的にReflectionEnumUnitCaseとして機能します。
39    $reflectionCase = $reflectionEnum->getCase('ACTIVE');
40
41    // このケースがBacked Enum（値を持つEnum）ではないことを確認（Unit Enumであることを確認）
42    if ($reflectionCase->isBacked()) {
43        echo "エラー: このケースはBacked Enumであり、Unit Enumではありません。\n";
44        return;
45    }
46    echo "リフレクション対象のEnumケースはUnit Enumです (isBacked(): " . ($reflectionCase->isBacked() ? 'true' : 'false') . ")\n\n";
47
48    // 4. getValue() メソッドを使って、Enumケースのインスタンスを取得
49    // 戻り値は UnitEnum（今回の場合は Status::ACTIVE のインスタンス）です。
50    $retrievedEnumInstance = $reflectionCase->getValue();
51
52    echo "リフレクション経由で取得した値の型: " . get_class($retrievedEnumInstance) . "\n";
53    echo "リフレクション経由で取得した値の名前: " . $retrievedEnumInstance->name . "\n\n";
54
55    // 5. 取得した値が元のEnumケースインスタンスと同一であることを検証
56    if ($retrievedEnumInstance === $originalStatus) {
57        echo "検証結果: リフレクション経由で取得した値は、元のEnumケースインスタンスと同一です。\n";
58    } else {
59        echo "検証結果: エラー - 取得した値が元のEnumケースインスタンスと異なります。\n";
60    }
61}
62
63// サンプルコードを実行
64demonstrateReflectionEnumUnitCaseGetValue();

PHP 8.1で導入されたUnit Enum（値を持たない列挙型）は、名前だけで意味を表す定数セットを定義します。ReflectionEnumUnitCase::getValue()メソッドは、このようなUnit Enumの特定のケースに対応するリフレクションオブジェクトから、そのEnumケース自体のインスタンスを取得するために使用されます。

このメソッドは引数を取りません。戻り値としては、対象のUnitEnumインターフェースを実装したEnumケースのインスタンス（例: Status::ACTIVE）を返します。

サンプルコードでは、まずStatusというUnit Enumを定義しています。次に、ReflectionEnumクラスを使ってEnum全体の情報を取得し、getCase('ACTIVE')メソッドで特定のEnumケース「ACTIVE」に対応するReflectionEnumCaseオブジェクトを取得します。このReflectionEnumCaseオブジェクトがUnit Enumのケースを指している場合、getValue()を呼び出すことで、Status::ACTIVEというEnumインスタンスそのものを取得できます。取得されたインスタンスは、元のインスタンスと全く同じオブジェクトであることが確認できます。

ReflectionEnumUnitCaseはPHP内部クラスのため直接インスタンス化できませんが、ReflectionEnum::getCase()などがUnit Enumのケースを返す場合は、そのReflectionEnumCaseオブジェクトがReflectionEnumUnitCaseと同様に振る舞います。これにより、実行時にEnumケースのインスタンスを動的に取得し、操作することが可能になります。

Copy
1<?php
2
3/**
4 * PHP 8.1 で導入されたユニット列挙型（Unit Enum）の例です。
5 * ユニット列挙型は、各ケースにスカラー値が関連付けられていない列挙型です。
6 */
7enum TrafficLightStatus
8{
9    case RED;
10    case YELLOW;
11    case GREEN;
12}
13
14/**
15 * ReflectionEnumUnitCase::getValue() メソッドの使用方法をデモンストレーションします。
16 * このメソッドは、ReflectionEnumUnitCase オブジェクトが表す
17 * 実際の UnitEnum インスタンス（列挙型ケース自身）を取得するために使用されます。
18 */
19function demonstrateReflectionEnumUnitCaseGetValue(): void
20{
21    // リフレクション対象のユニット列挙型ケースを選択します。
22    // ここでは TrafficLightStatus::YELLOW を使用します。
23    $enumCaseInstance = TrafficLightStatus::YELLOW;
24
25    // 列挙型全体のリフレクションオブジェクトを取得します。
26    $reflectionEnum = new ReflectionEnum(TrafficLightStatus::class);
27
28    // 特定の列挙型ケースに対するリフレクションオブジェクトを取得します。
29    // ReflectionEnum::getCase() メソッドは、指定された名前のケースのリフレクションを返します。
30    // ユニット列挙型の場合、これは ReflectionEnumUnitCase のインスタンスになります。
31    $reflectionUnitCase = $reflectionEnum->getCase($enumCaseInstance->name);
32
33    // 取得したリフレクションオブジェクトが ReflectionEnumUnitCase のインスタンスであることを確認します。
34    if ($reflectionUnitCase instanceof ReflectionEnumUnitCase) {
35        echo "--- ReflectionEnumUnitCase::getValue() の使用例 ---\n";
36
37        // ReflectionEnumUnitCase::getValue() を呼び出して、
38        // このリフレクションが表す実際の UnitEnum インスタンスを取得します。
39        // 引数なしで呼び出され、UnitEnum 型の値を返します。
40        $actualEnumValue = $reflectionUnitCase->getValue();
41
42        echo "リフレクションされたケースの名前: " . $reflectionUnitCase->getName() . "\n";
43        echo "getValue() で取得した値の型: " . get_debug_type($actualEnumValue) . "\n";
44        echo "getValue() で取得した値: ";
45        var_dump($actualEnumValue);
46
47        // 取得した値が、元の列挙型インスタンスと同一であるかを確認します。
48        if ($actualEnumValue === $enumCaseInstance) {
49            echo "結果: getValue() で取得した値は、元の列挙型インスタンスと同一です。\n";
50        } else {
51            echo "結果: エラーが発生しました。取得した値が元の列挙型インスタンスと異なります。\n";
52        }
53    } else {
54        echo "エラー: '" . $enumCaseInstance->name . "' のリフレクションオブジェクトが ReflectionEnumUnitCase ではありません。\n";
55    }
56}
57
58// デモンストレーション関数を実行します。
59demonstrateReflectionEnumUnitCaseGetValue();

PHP 8.1で導入されたReflectionEnumUnitCase::getValue()メソッドは、PHPのリフレクションAPIの一部であり、ユニット列挙型（Unit Enum）の内部情報を動的に扱う際に使用されます。このメソッドは、引数を一切取らず、呼び出すと、そのReflectionEnumUnitCaseオブジェクトが表す実際のユニット列挙型インスタンス（UnitEnum型のオブジェクト）そのものを返します。

ユニット列挙型とは、case RED; case YELLOW;のように、各ケースにスカラー値が関連付けられていないシンプルな列挙型のことです。getValue()は、こうした列挙型ケースのメタデータを通じて、プログラム実行中に特定の列挙型ケースそのものを動的に取得したい場合に非常に役立ちます。

サンプルコードでは、TrafficLightStatus::YELLOWというユニット列挙型ケースを例に、ReflectionEnumを通じてそのケースに対応するReflectionEnumUnitCaseオブジェクトを取得しています。そして、取得した$reflectionUnitCaseに対してgetValue()メソッドを呼び出すことで、TrafficLightStatus::YELLOWという実際のインスタンスが取得される様子を示しています。これにより、リフレクションを通じて取得した列挙型ケースの情報から、定義された列挙型ケースそのものをプログラム内で操作することが可能となります。例えば、取得したインスタンスを他の関数に渡したり、厳密な型チェックを行ったりする際に活用できます。