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

Copy
1<?php
2
3// PHP 8.1で導入されたBacked Enum（バッキング型を持つ列挙型）を定義します。
4// 各ケースに文字列または整数値を関連付けることができます。
5// ここでは文字列型のバッキング値を持つEnumを例とします。
6enum UserRole: string
7{
8    case Admin = 'administrator';
9    case Editor = 'editor';
10    case Viewer = 'viewer';
11}
12
13// リフレクションAPIを使用して、UserRole Enumの情報を取得します。
14// ReflectionEnumクラスは、Enumに関する情報を実行時に検査することを可能にします。
15$enumReflection = new ReflectionEnum(UserRole::class);
16
17echo "--- UserRole Enumのバッキング値の取得 ---\n";
18
19// Enumのすべてのケースをループ処理します。
20foreach ($enumReflection->getCases() as $caseReflection) {
21    // getBackingValue() メソッドは ReflectionEnumBackedCase クラスに属しています。
22    // そのため、現在のケースがBacked Enumのケースであることを確認します。
23    // Backed EnumのケースはReflectionEnumBackedCaseインスタンスとして表現されます。
24    if ($caseReflection instanceof ReflectionEnumBackedCase) {
25        // ケースの名前を表示します。
26        echo "ケース名: " . $caseReflection->getName() . "\n";
27
28        // getBackingValue() メソッドを使用して、
29        // ケースに関連付けられた文字列または整数型のバッキング値を取得します。
30        $backingValue = $caseReflection->getBackingValue();
31
32        // 取得したバッキング値と、そのデータ型を表示します。
33        echo "バッキング値: " . $backingValue . " (型: " . gettype($backingValue) . ")\n";
34        echo "-----------------------------------------\n";
35    }
36}
37
38?>

ReflectionEnumBackedCase::getBackingValueメソッドは、PHP 8.1で導入されたバッキング型を持つ列挙型（Backed Enum）の各ケースに割り当てられた具体的な値、つまり「バッキング値」を取得するために使用されます。このメソッドは、プログラムが自身の構造を動的に調べられる「リフレクションAPI」の一部で、実行時にEnumの情報を検査する際に役立ちます。

引数はなく、シンプルに呼び出すだけで、対象のEnumケースに設定されたバッキング値を取得できます。戻り値は、Enumが定義された際に指定された型に応じて、文字列（string）または整数（int）のいずれかになります。

サンプルコードでは、UserRoleという文字列型のバッキング値を持つBacked Enumを定義しています。ReflectionEnumクラスを使ってUserRole Enum全体の情報を取得した後、getCases()メソッドで各ケースを一つずつ取り出しています。取り出したケースがReflectionEnumBackedCaseのインスタンスである場合に、getBackingValue()メソッドを呼び出すことで、例えばAdminケースから'administrator'という文字列値を取得しています。このように、このメソッドを使うことで、Enumの各ケースが持つ具体的な値をプログラムから効率的に取得し、活用することが可能になります。

Copy
1<?php
2
3/**
4 * PHP 8.1で導入されたBacked Enumの例。
5 * PHP 8.0以前ではEnumは利用できません。
6 * Backed Enumの各ケースは、文字列または整数値のバッキング値を持つことができます。
7 */
8enum UserStatus: string
9{
10    case Active = 'active';
11    case Inactive = 'inactive';
12    case Pending = 'pending';
13    case Deleted = 'deleted';
14}
15
16/**
17 * ReflectionEnumBackedCase::getBackingValue() メソッドの使用例を示します。
18 * このメソッドは、バッキングされたEnumケースのバッキング値を取得します。
19 * システムエンジニアを目指す初心者向けに、Enumのリフレクションの基本的な流れを解説します。
20 */
21function demonstrateGetBackingValueUsage(): void
22{
23    // リフレクション対象のEnumクラス名を指定します。
24    $enumClass = UserStatus::class;
25
26    // 特定のBacked Enumケースの名前を指定します。
27    $caseName = 'Active';
28
29    try {
30        // 1. ReflectionEnumオブジェクトを作成し、Enum全体のリフレクション情報を取得します。
31        //    これにより、Enumの構造やケースに関する情報を調べることができます。
32        $reflectionEnum = new ReflectionEnum($enumClass);
33
34        // 2. 指定したケース名に対応するEnumケースのリフレクションオブジェクトを取得します。
35        //    getCase()メソッドは、ReflectionEnumCaseの子孫オブジェクトを返します。
36        //    Backed Enum（バッキング値を持つEnum）の場合、ReflectionEnumBackedCaseのインスタンスを返します。
37        //    Unit Enum（バッキング値を持たないEnum）の場合、ReflectionEnumUnitCaseのインスタンスを返します。
38        $reflectionCase = $reflectionEnum->getCase($caseName);
39
40        // 3. 取得したリフレクションオブジェクトが ReflectionEnumBackedCase のインスタンスであることを確認します。
41        //    getBackingValue() メソッドは、ReflectionEnumBackedCaseクラスでのみ利用可能です。
42        if ($reflectionCase instanceof ReflectionEnumBackedCase) {
43            // 4. getBackingValue() を呼び出して、Enumケースに設定されたバッキング値を取得します。
44            //    このメソッドは引数をとりません。
45            $backingValue = $reflectionCase->getBackingValue();
46
47            echo "Enumクラス名: " . $enumClass . "\n";
48            echo "Enumケース名: " . $reflectionCase->getName() . "\n";
49            echo "取得されたバッキング値: " . $backingValue . " (型: " . gettype($backingValue) . ")\n";
50        } else {
51            // バッキングされていないEnumケース、または指定されたケースが見つからない場合のメッセージです。
52            echo "Enumケース '" . $caseName . "' はバッキングされていません。getBackingValue() は使用できません。\n";
53        }
54    } catch (ReflectionException $e) {
55        // Enumクラスが見つからない、または指定されたケースが存在しない場合のエラーハンドリングです。
56        echo "エラーが発生しました: " . $e->getMessage() . "\n";
57    }
58
59    echo "\n"; // 出力を見やすくするための改行
60
61    // 別のBacked Enumケースで同じ処理を繰り返す例です。
62    $caseName = 'Deleted';
63    try {
64        $reflectionEnum = new ReflectionEnum($enumClass);
65        $reflectionCase = $reflectionEnum->getCase($caseName);
66
67        if ($reflectionCase instanceof ReflectionEnumBackedCase) {
68            $backingValue = $reflectionCase->getBackingValue();
69            echo "Enumクラス名: " . $enumClass . "\n";
70            echo "Enumケース名: " . $reflectionCase->getName() . "\n";
71            echo "取得されたバッキング値: " . $backingValue . " (型: " . gettype($backingValue) . ")\n";
72        } else {
73            echo "Enumケース '" . $caseName . "' はバッキングされていません。getBackingValue() は使用できません。\n";
74        }
75    } catch (ReflectionException $e) {
76        echo "エラーが発生しました: " . $e->getMessage() . "\n";
77    }
78}
79
80// 上記で定義した関数を実行して、処理を開始します。
81demonstrateGetBackingValueUsage();

PHP 8.1で導入されたEnumは、名前付きの定数をグループ化する機能です。特に「Backed Enum」と呼ばれる形式では、各ケース（定数）に文字列または整数値の具体的な「バッキング値」を持たせることができます。このサンプルコードは、PHPのリフレクション機能を使って、このBacked Enumのバッキング値を動的に取得する方法を示しています。

リフレクションとは、プログラムの実行中にクラスやメソッド、Enumといった構造の情報を調べたり操作したりする強力な機能です。ReflectionEnumBackedCaseクラスは、Backed Enumの個々のケースに関する詳細な情報を提供します。

ReflectionEnumBackedCase::getBackingValue()メソッドは、引数なしで呼び出すことができ、そのBacked Enumケースに設定されたバッキング値を取得します。戻り値の型は、そのEnumが定義された際のバッキング型に応じてstringまたはintとなります。

サンプルコードでは、まずUserStatusというBacked Enumを定義しています。次に、demonstrateGetBackingValueUsage()関数内で、ReflectionEnumオブジェクトを作成し、そこから特定のケース名（例: 'Active'）に対応するReflectionEnumBackedCaseオブジェクトを取得しています。そして、このオブジェクトに対してgetBackingValue()を呼び出すことで、Enumケース 'Active' のバッキング値である 'active' を取得し、その値と型を表示しています。このように、実行時にEnumの構造を調べ、バッキング値にアクセスすることが可能になります。