【PHP8.x】ReflectionEnumUnitCase::nameプロパティの使い方

Copy
1<?php
2
3namespace App\Enums; // キーワード「php namespace」に従い、Enumを名前空間内に定義します。
4
5/**
6 * ユニットEnum（値を持たないシンプルなEnum）の例です。
7 * 各ケースは独自の値を持ちません。
8 */
9enum Status
10{
11    case Active;
12    case Inactive;
13    case Pending;
14}
15
16/**
17 * ReflectionEnumUnitCase::name プロパティの使用方法を示す関数です。
18 * Enumケースの名前をリフレクションAPIを使って取得します。
19 */
20function demonstrateReflectionEnumUnitCaseName(): void
21{
22    // Reflection APIを使用して、定義したEnum（App\Enums\Status）のリフレクションクラスを取得します。
23    // これにより、Enum自体の情報（ケースなど）にプログラムからアクセスできるようになります。
24    $reflectionEnum = new \ReflectionEnum(Status::class);
25
26    echo "--- Enum Unit Cases and their names using Reflection ---" . PHP_EOL;
27
28    // Enumの各ケースをループ処理します。
29    // getCases() メソッドは、Enumの各ケースを表すReflectionEnumUnitCaseまたはReflectionEnumBackedCaseの配列を返します。
30    foreach ($reflectionEnum->getCases() as $case) {
31        // この例ではユニットEnumを使用しているため、$caseはReflectionEnumUnitCaseのインスタンスになります。
32        if ($case instanceof \ReflectionEnumUnitCase) {
33            // ReflectionEnumUnitCase::name プロパティは、Enumケースの名前を文字列として返します。
34            echo "Case Name: " . $case->name . PHP_EOL;
35        }
36    }
37}
38
39// 上記の関数を実行し、Enumケースの名前を出力します。
40demonstrateReflectionEnumUnitCaseName();

PHPのリフレクションAPIは、プログラムの実行中にクラスやメソッド、Enumなどの構造を調べ、動的に操作するための機能です。このサンプルコードでは、PHP 8で導入されたEnum（列挙型）のケース名を、リフレクションAPIを使って取得する方法を示しています。

まず、App\Enumsという名前空間内に、値を持たないシンプルなEnum「Status」を定義しています。名前空間を使用することで、関連するコードを整理し、他の部分との名前の衝突を防ぐことができます。

次に、demonstrateReflectionEnumUnitCaseName関数内で、ReflectionEnumクラスを用いてStatus Enum全体の情報を取得します。これにより、プログラムからEnumの内部構造にアクセスできるようになります。getCases()メソッドを使用すると、Enumが持つ各ケース（例えばActiveやInactive）を表すオブジェクトの配列が返されます。

この配列内の各オブジェクトは、値を持たないユニットEnumの場合、ReflectionEnumUnitCaseのインスタンスです。ReflectionEnumUnitCaseクラスのnameプロパティは、そのEnumケースが定義された際の具体的な名前を文字列として返します。このプロパティは引数を必要とせず、Enumケースの識別子そのものである「Active」や「Inactive」といった名前を正確に取得することができます。これにより、プログラムはEnumのケース名を動的に把握し、活用することが可能になります。

Copy
1<?php
2
3namespace MyApp\Enums; // ネームスペースは、コードを整理し、クラスや関数の名前の衝突を防ぐために使われます。
4                        // 一般的に「ベンダー名\モジュール名\サブモジュール」のような命名規則（PSR-4に準拠）が推奨されます。
5
6/**
7 * 注文のステータスを表す列挙型（Enum）。
8 * PHP 8.1以降で導入された機能です。
9 * `ReflectionEnumUnitCase`は、このように値を持たない純粋なEnumケース（Pure Enum）をリフレクションする際に使用します。
10 */
11enum OrderStatus
12{
13    case PENDING;    // 注文が保留中の状態
14    case COMPLETED;  // 注文が完了した状態
15    case CANCELLED;  // 注文がキャンセルされた状態
16}
17
18/**
19 * 指定された列挙型クラスから特定のケースの名前を取得する関数。
20 * `ReflectionEnumUnitCase::name`プロパティを使用して、Enumケースの宣言名を文字列として取得します。
21 *
22 * @param string $enumClassName 列挙型クラスの完全修飾名 (例: MyApp\Enums\OrderStatus::class)
23 * @param string $caseName      取得したいEnumケースの宣言名 (例: 'PENDING')
24 * @return string|null          Enumケース名が見つかった場合はその名前、それ以外はnull
25 */
26function getEnumCaseName(string $enumClassName, string $caseName): ?string
27{
28    try {
29        // `ReflectionEnum` を使用して、Enum全体の情報（ケースやメソッドなど）にアクセスします。
30        $reflectionEnum = new \ReflectionEnum($enumClassName);
31
32        // `getCase()` メソッドで、指定した名前のEnumケースに対応する`ReflectionEnumUnitCase`
33        // または `ReflectionEnumBackedCase` のインスタンスを取得します。
34        // 今回の`OrderStatus`はPure Enumのため、`ReflectionEnumUnitCase`が返されます。
35        $reflectionCase = $reflectionEnum->getCase($caseName);
36
37        // `ReflectionEnumUnitCase::name` プロパティは、
38        // そのEnumケースが定義された際の文字列としての名前を返します。
39        // 例えば、`case PENDING;` の場合は "PENDING" という文字列が取得されます。
40        return $reflectionCase->name;
41
42    } catch (\ReflectionException $e) {
43        // 指定されたEnumクラス名が不正な場合や、ケースが見つからない場合に例外をキャッチします。
44        echo "エラー発生: " . $e->getMessage() . PHP_EOL;
45        return null;
46    }
47}
48
49// --- サンプルコードの実行例 ---
50
51// 定義した`OrderStatus` Enumクラスの完全修飾名（namespaceを含む）を指定します。
52// `::class`定数を使用すると、クラスの完全修飾名を文字列として取得できます。
53$enumClass = OrderStatus::class; // これは 'MyApp\\Enums\\OrderStatus' という文字列になります。
54
55echo "--- Enumケース名の取得 ---" . PHP_EOL;
56
57// 「PENDING」ケースの名前を取得して表示します。
58$pendingCaseName = getEnumCaseName($enumClass, 'PENDING');
59if ($pendingCaseName !== null) {
60    echo "取得されたEnumケース名 (PENDING): " . $pendingCaseName . PHP_EOL;
61}
62
63// 「COMPLETED」ケースの名前を取得して表示します。
64$completedCaseName = getEnumCaseName($enumClass, 'COMPLETED');
65if ($completedCaseName !== null) {
66    echo "取得されたEnumケース名 (COMPLETED): " . $completedCaseName . PHP_EOL;
67}
68
69// 存在しないケース名を指定した場合の例
70echo PHP_EOL . "--- 存在しないEnumケースの取得試行 ---" . PHP_EOL;
71$nonExistentCaseName = getEnumCaseName($enumClass, 'PROCESSING');
72if ($nonExistentCaseName === null) {
73    echo "指定された 'PROCESSING' ケースは存在しないため、名前を取得できませんでした。" . PHP_EOL;
74}
75
76?>

PHP 8.1で導入された列挙型（Enum）は、定数をまとめて管理するための便利な機能です。ReflectionEnumUnitCaseクラスは、このEnumの中でも、値を持たない純粋なケース（例えば case PENDING; のような定義）に関する情報を、プログラム実行中に動的に取得するために使用されます。

このReflectionEnumUnitCaseクラスのnameプロパティは、引数なしで呼び出され、該当するEnumケースが宣言された際の文字列としての名前をstring型で返します。例えば、case PENDING;と定義されたEnumケースに対しては"PENDING"という文字列が取得されます。

サンプルコードでは、まずMyApp\Enumsというnamespace（名前空間）を定義し、コードの整理とクラス名の衝突防止に役立てています。namespaceの命名規則は、一般的にPSR-4などの標準に準拠することが推奨されます。OrderStatusという純粋なEnumが定義され、getEnumCaseName関数がReflectionEnumクラスを用いて、指定されたEnumクラスから特定のケースのReflectionEnumUnitCaseインスタンスを取得し、そのnameプロパティを通じてケース名を動的に取得する仕組みを示しています。この関数は、Enumクラスの完全修飾名と調べたいケース名を引数として受け取り、見つかればケース名を文字列で、見つからなければnullを戻り値として返します。これにより、実行時にEnumのケース名を簡単に取得し、利用することが可能になります。