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

Copy
1<?php
2
3// PHP 8.1 以降で利用可能な、バックアップ値を持つ列挙型（Backed Enum）を定義します。
4// Backed Enum は、int または string のスカラー値をバックアップ値として持ちます。
5enum StatusCode: int
6{
7    case OK = 200;
8    case BadRequest = 400;
9    case NotFound = 404;
10    case InternalServerError = 500;
11}
12
13// BackedEnum クラスの静的メソッド `cases()` を呼び出し、
14// その列挙型に定義されている全てのケースを配列として取得します。
15// このメソッドは引数を取りません。
16$allStatusCodes = StatusCode::cases();
17
18echo "StatusCode Enum の全てのケース:\n";
19
20// 取得した配列をループ処理し、各ケースの情報（名前とバックアップ値）を表示します。
21foreach ($allStatusCodes as $case) {
22    // 各要素は列挙型インスタンスであり、`name` プロパティでケースの名前、
23    // `value` プロパティでそのバックアップ値にアクセスできます。
24    echo "- ケース名: " . $case->name . ", バックアップ値: " . $case->value . "\n";
25}
26

PHP 8.1以降の「バックアップ値を持つ列挙型（Backed Enum）」は、定数名に加えて、整数や文字列のスカラー値を関連付ける機能です。本サンプルコードでは、HTTPステータスコードを整数値として持つStatusCodeというBacked Enumを定義しています。

StatusCode::cases()は、このBacked Enumに定義されている全てのケースを効率的に取得する静的メソッドです。引数は不要で、呼び出すと、各列挙型ケースのインスタンスを要素とする配列が戻り値として返されます。

取得した配列$allStatusCodesをforeachでループ処理すると、各列挙型ケースのインスタンスにアクセスできます。各インスタンスからは、nameプロパティでケースの名前（例: OK）、valueプロパティでそのバックアップ値（例: 200）を取り出せます。これは、定義された全列挙型ケースの情報を動的に取得し、プログラムで利用する際に大変有用です。

Copy
1<?php
2
3/**
4 * BackedEnum の利用例として、注文ステータスを表す列挙型を定義します。
5 * PHP 8.1 以降で利用可能な機能です。
6 */
7enum OrderStatus: string
8{
9    case PENDING = 'pending';
10    case COMPLETED = 'string';
11    case CANCELLED = 'cancelled';
12
13    /**
14     * Enum の値に基づいて、より詳細な説明を返すメソッド。
15     * これは `cases()` メソッドの使用とは直接関係ありませんが、Enum の一般的な使い方を示します。
16     *
17     * @return string
18     */
19    public function getDescription(): string
20    {
21        return match ($this) {
22            self::PENDING => '注文は処理待ちです。',
23            self::COMPLETED => '注文は完了しました。',
24            self::CANCELLED => '注文はキャンセルされました。',
25        };
26    }
27}
28
29/**
30 * BackedEnum::cases() メソッドを使用して、Enum の全てのケースを取得し、表示するサンプルです。
31 */
32function demonstrateBackedEnumCases(): void
33{
34    echo "--- OrderStatus Enum の全ケース ---" . PHP_EOL;
35
36    // OrderStatus 列挙型の全てのケース（インスタンス）を配列として取得します。
37    // BackedEnum::cases() は引数を取りません。
38    $allCases = OrderStatus::cases();
39
40    // 取得した各ケースについて、名前と値、そして説明を表示します。
41    foreach ($allCases as $case) {
42        // 各ケースの「名前」（定義された定数名）を取得します。
43        echo "名前: " . $case->name . PHP_EOL;
44
45        // 各ケースの「値」（バックアップされたスカラ値）を取得します。
46        echo "値: " . $case->value . PHP_EOL;
47
48        // Enum 内で定義したメソッドを使って、ケースの説明を表示します。
49        echo "説明: " . $case->getDescription() . PHP_EOL;
50        echo "--------------------------" . PHP_EOL;
51    }
52}
53
54// サンプルコードを実行します。
55demonstrateBackedEnumCases();
56
57?>

PHP 8.1以降で導入されたenum（列挙型）は、複数の状態を定数として管理する際に役立つ機能です。このサンプルコードは、特にバックアップ型列挙型（BackedEnum）に焦点を当て、その中のcases()メソッドの利用方法を具体的に示しています。

BackedEnum::cases()メソッドは、引数を一切取らず、呼び出された列挙型に定義されている全てのケース（列挙子）を配列として取得するために使用されます。戻り値は、各ケースのインスタンスが格納された配列です。

このサンプルコードでは、注文の状態を表すOrderStatusという列挙型を定義しています。demonstrateBackedEnumCases()関数内でOrderStatus::cases()を呼び出すことで、PENDING、COMPLETED、CANCELLEDといった全ての注文ステータスのケースが配列として取得されます。その後、取得した配列をループ処理し、各ケースのnameプロパティから定義された名前（例: 'PENDING'）を、valueプロパティからバックアップされた値（例: 'pending'）をそれぞれ取得して表示しています。これにより、列挙型の全ての要素をプログラム的に扱い、その名前と値にアクセスする方法を理解することができます。複数の状態を扱うシステムにおいて、動的に全ケースを取得し処理する際に非常に便利なメソッドです。