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

Copy
1<?php
2
3// PHP 8.1 で導入されたBacked Enum（バッキングを持つ列挙型）を定義します。
4// バッキングとは、各Enumケースに特定の型（intまたはstring）の値を関連付けることです。
5enum UserStatus: int
6{
7    case Active = 1;
8    case Inactive = 0;
9    case Pending = 2;
10}
11
12enum UserRole: string
13{
14    case Admin = 'administrator';
15    case Editor = 'editor';
16    case Viewer = 'viewer';
17}
18
19/**
20 * ReflectionEnumBackedCase::getValue() メソッドの使用例を示します。
21 *
22 * このメソッドは、バッキングを持つEnum（列挙型）の特定のケースに関連付けられた
23 * バッキング値（int または string）を取得するために使用されます。
24 *
25 * システムエンジニアを目指す初心者向けに、リフレクションの基本的な使い方と、
26 * Enumのバッキング値の取得方法を簡潔に説明します。
27 */
28function demonstrateReflectionEnumBackedCaseGetValue(): void
29{
30    echo "--- int 型のバッキング値を持つEnumの例 ---" . PHP_EOL;
31
32    // ReflectionEnum クラスを使って UserStatus Enum 全体のリフレクション情報を取得します。
33    // リフレクションとは、実行時にクラス、メソッド、プロパティなどの情報を
34    // 調べるための機能です。
35    $reflectionEnumStatus = new ReflectionEnum(UserStatus::class);
36
37    // 特定のEnumケース（ここでは 'Active'）のリフレクション情報を取得します。
38    // getCase() メソッドは ReflectionEnumUnitCase または ReflectionEnumBackedCase を返します。
39    $reflectionCaseActive = $reflectionEnumStatus->getCase('Active');
40
41    // 取得したケースが ReflectionEnumBackedCase のインスタンスであることを確認します。
42    // Backed Enum（バッキングを持つEnum）の場合、この型になります。
43    if ($reflectionCaseActive instanceof ReflectionEnumBackedCase) {
44        // getValue() メソッドを呼び出して、'Active' ケースのバッキング値を取得します。
45        // このケースでは 'Active' には整数 '1' が関連付けられています。
46        $activeValue = $reflectionCaseActive->getValue();
47
48        echo "Enumケース名: " . $reflectionCaseActive->getName() . PHP_EOL; // 出力: Active
49        echo "取得されたバッキング値: " . $activeValue . PHP_EOL;        // 出力: 1
50        echo "バッキング値の型: " . gettype($activeValue) . PHP_EOL;     // 出力: integer
51    } else {
52        echo "エラー: UserStatus::Active は ReflectionEnumBackedCase ではありません。" . PHP_EOL;
53    }
54
55    echo PHP_EOL; // 改行
56
57    echo "--- string 型のバッキング値を持つEnumの例 ---" . PHP_EOL;
58
59    // UserRole Enum についても同様に処理します。
60    $reflectionEnumRole = new ReflectionEnum(UserRole::class);
61    $reflectionCaseAdmin = $reflectionEnumRole->getCase('Admin');
62
63    if ($reflectionCaseAdmin instanceof ReflectionEnumBackedCase) {
64        // getValue() メソッドで 'Admin' ケースのバッキング値を取得します。
65        // このケースでは 'Admin' には文字列 'administrator' が関連付けられています。
66        $adminValue = $reflectionCaseAdmin->getValue();
67
68        echo "Enumケース名: " . $reflectionCaseAdmin->getName() . PHP_EOL; // 出力: Admin
69        echo "取得されたバッキング値: " . $adminValue . PHP_EOL;         // 出力: administrator
70        echo "バッキング値の型: " . gettype($adminValue) . PHP_EOL;      // 出力: string
71    } else {
72        echo "エラー: UserRole::Admin は ReflectionEnumBackedCase ではありません。" . PHP_EOL;
73    }
74}
75
76// 上記で定義したデモンストレーション関数を実行します。
77demonstrateReflectionEnumBackedCaseGetValue();
78

このサンプルコードは、PHP 8.1で導入されたBacked Enum（バッキングを持つ列挙型）における、特定のEnumケースのバッキング値を取得する方法をReflection機能を使って示しています。Backed Enumとは、各Enumケースにint型またはstring型の具体的な値を関連付けた列挙型のことです。

Reflectionとは、プログラムが実行されている最中に、クラス、メソッド、プロパティなどの内部情報を動的に調べることができる機能です。このコードでは、ReflectionEnumBackedCaseクラスのgetValue()メソッドを使用します。

getValue()メソッドは引数を取りません。その役割は、ReflectionEnumBackedCaseインスタンスが表すEnumケースに設定されているバッキング値をそのまま返すことです。戻り値は、Enumの定義に応じてint型またはstring型となります。

コードではまず、UserStatusというint型のバッキング値を持つEnumと、UserRoleというstring型のバッキング値を持つEnumを定義しています。次に、ReflectionEnumクラスを使ってこれらのEnumの情報を取得し、getCase()メソッドで特定のEnumケース（例: UserStatus::ActiveやUserRole::Admin）のReflectionEnumBackedCaseインスタンスを取得します。最後に、取得したインスタンスに対してgetValue()を呼び出すことで、Activeケースからは整数1が、Adminケースからは文字列administratorがそれぞれ取得される様子が確認できます。これにより、実行時にEnumのバッキング値にアクセスし、柔軟な処理を実現することが可能です。

Copy
1<?php
2
3// PHP 8.1以降で導入されたBacked Enumを定義します。
4// Enum（列挙型）は、名前付きの定数群を型安全に扱うための機能です。
5// Backed Enumは、各ケースにintまたはstringのスカラー値（バックアップ値）を紐付けます。
6enum StatusCode: int
7{
8    case Success = 200;
9    case NotFound = 404;
10    case InternalServerError = 500;
11}
12
13/**
14 * Backed Enumのケースからバックアップ値を取得する方法を示すサンプル関数です。
15 *
16 * Reflection APIは、プログラムの実行中にクラス、メソッド、プロパティなどの構造を
17 * 検査・操作するための強力な機能です。
18 * この例では、ReflectionEnumBackedCaseクラスとそのgetValueメソッドを使用して、
19 * Enumのケースに紐付けられた具体的なバックアップ値を取得します。
20 *
21 * @requires PHP 8.1.0 or higher for Backed Enum and ReflectionEnumBackedCase.
22 */
23function demonstrateReflectionEnumBackedCaseGetValue(): void
24{
25    // 対象とするEnumケースのオブジェクトを取得します。
26    $targetCase = StatusCode::NotFound;
27
28    try {
29        // ReflectionEnumBackedCaseのインスタンスを作成します。
30        // これにより、指定したBacked Enumの特定のケースに関する詳細情報を
31        // プログラムから取得できるようになります。
32        // コンストラクタには、Enumのクラス名とケース名を渡します。
33        $reflectionCase = new ReflectionEnumBackedCase(StatusCode::class, $targetCase->name);
34
35        // getValue()メソッドを呼び出して、Enumケースに紐付けられたバックアップ値を取得します。
36        // このメソッドは、Backed Enumの定義に応じてintまたはstringを返します。
37        $backedValue = $reflectionCase->getValue();
38
39        echo "Enumケース '{$targetCase->name}' のバックアップ値: {$backedValue}\n";
40        echo "バックアップ値の型: " . gettype($backedValue) . "\n\n";
41
42        // 別のEnumケースで試してみましょう。
43        $targetCase = StatusCode::Success;
44        $reflectionCase = new ReflectionEnumBackedCase(StatusCode::class, $targetCase->name);
45        $backedValue = $reflectionCase->getValue();
46
47        echo "Enumケース '{$targetCase->name}' のバックアップ値: {$backedValue}\n";
48        echo "バックアップ値の型: " . gettype($backedValue) . "\n";
49
50    } catch (ReflectionException $e) {
51        // Reflection APIの使用中にエラーが発生した場合（例: 存在しないEnumケースを指定）、
52        // ReflectionExceptionがスローされます。
53        echo "Reflectionエラーが発生しました: " . $e->getMessage() . "\n";
54    }
55}
56
57// サンプル関数を実行します。
58demonstrateReflectionEnumBackedCaseGetValue();
59
60?>

PHPのReflectionEnumBackedCase::getValue()メソッドは、PHP 8.1で導入された「Backed Enum（バックアップ値付き列挙型）」の特定のケースに紐付けられた具体的な値を取得するために使用します。Backed Enumは、case Success = 200;のように、各列挙型ケースに整数または文字列のスカラー値を関連付ける機能です。このメソッドは、プログラム実行時にEnumの構造を調べ、ケースに設定されたバックアップ値を動的に取得する際に役立ちます。

サンプルコードでは、まずHTTPステータスコードをバックアップ値とするStatusCodeというBacked Enumを定義しています。次に、ReflectionEnumBackedCaseクラスのインスタンスを生成し、特定のEnumケース（例：StatusCode::NotFound）に関するリフレクション情報（反射情報）を取得します。このインスタンスに対して、引数なしでgetValue()メソッドを呼び出すと、そのEnumケースに紐付けられたバックアップ値（この場合は404）が返されます。戻り値は、Enumの定義に応じてint型またはstring型となります。これにより、コード内でEnumの値を直接参照するだけでなく、実行時にEnumの値を検査・利用できるようになります。