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

Copy
1<?php
2
3/**
4 * BackedEnum をゼロから定義します。
5 * 各列挙ケースは、string または int のスカラー値を持ちます。
6 * ここでは注文のステータスを表す文字列値を持ちます。
7 */
8enum OrderStatus: string
9{
10    case PENDING = 'pending';   // 注文は保留中
11    case APPROVED = 'approved'; // 注文は承認済み
12    case REJECTED = 'rejected'; // 注文は拒否済み
13    case SHIPPED = 'shipped';   // 注文は発送済み
14}
15
16/**
17 * BackedEnum::from メソッドの使用例を示します。
18 * これは、指定された文字列または整数値から Enum ケースのインスタンスを取得します。
19 *
20 * @param string $statusValue 取得したい Enum ケースに対応するバッキング値
21 * @return void
22 */
23function demonstrateBackedEnumFrom(string $statusValue): void
24{
25    echo "--- BackedEnum::from メソッドのデモンストレーション ---" . PHP_EOL;
26
27    try {
28        // 指定された値から OrderStatus の Enum インスタンスを生成します。
29        // 例えば、'pending' という文字列から OrderStatus::PENDING を取得します。
30        $orderStatus = OrderStatus::from($statusValue);
31
32        // 取得した Enum インスタンスの名前と値を出力します。
33        echo "与えられた値 '{$statusValue}' から取得したEnum: "
34            . "名前 = " . $orderStatus->name
35            . ", 値 = " . $orderStatus->value . PHP_EOL;
36
37    } catch (ValueError $e) {
38        // 指定された値に対応する Enum ケースが存在しない場合、ValueError がスローされます。
39        echo "エラー: '{$statusValue}' に対応するEnumケースが見つかりませんでした。(" . $e->getMessage() . ")" . PHP_EOL;
40    }
41    echo PHP_EOL;
42}
43
44// サンプルコードとして、いくつかの値で demonstrateBackedEnumFrom 関数を実行します。
45
46// 有効なバッキング値で実行
47demonstrateBackedEnumFrom('pending');
48demonstrateBackedEnumFrom('approved');
49demonstrateBackedEnumFrom('shipped');
50
51// 存在しないバッキング値で実行し、エラーハンドリングを示す
52demonstrateBackedEnumFrom('cancelled'); // この値は定義されていないため、エラーになります
53demonstrateBackedEnumFrom('completed'); // この値も定義されていないため、エラーになります
54

PHP 8から導入されたenum（列挙型）には、値を保持するBackedEnumがあります。BackedEnum::fromメソッドは、このBackedEnumの特定のケースを、そのケースが持つバッキング値（文字列または整数）を使って取得するための便利な機能です。

このメソッドは、string|int $valueという引数を受け取ります。この$valueには、取得したいEnumケースが持つ実際の値、例えばサンプルコードのOrderStatusで言えば'pending'や'approved'といった文字列を指定します。

処理が成功すると、指定されたバッキング値に対応するEnumケースのインスタンス（static）が戻り値として返されます。これにより、例えば'pending'という文字列からOrderStatus::PENDINGというEnumケースを直接取得できます。取得したEnumケースからは、その名前（nameプロパティ）とバッキング値（valueプロパティ）にアクセス可能です。

もし、指定された$valueに対応するEnumケースが存在しない場合は、ValueErrorというエラーがスローされます。サンプルコードでは、存在しない'cancelled'などを指定した場合にこのエラーが発生し、プログラムが停止しないようにtry-catchブロックで適切に処理していることが示されています。

このfromメソッドを使用することで、外部から文字列や数値として渡されたデータから、安全かつ簡潔にEnumケースのインスタンスを生成し、コードの可読性と堅牢性を高めることができます。

Copy
1<?php
2
3// PHP 8.1 で導入された Backed Enum (バッキング列挙型) を使用します。
4// Backed Enum は、各列挙型メンバーに特定のスカラー値 (int または string) を関連付けることができます。
5// ここでは、注文のステータスを表す Backed Enum を定義します。
6
7enum OrderStatus: string
8{
9    case Pending = 'pending';
10    case Processing = 'processing';
11    case Completed = 'completed';
12    case Cancelled = 'cancelled';
13
14    // Backed Enum は、バッキング値から列挙型メンバーを取得するための `from()` および `tryFrom()` メソッドを自動的に提供します。
15    // from() メソッドは、対応するバッキング値が存在しない場合に ValueError をスローします。
16    // tryFrom() メソッドは、対応するバッキング値が存在しない場合に null を返します。
17}
18
19/**
20 * BackedEnum::from() メソッドの基本的な使い方を示す関数です。
21 * 初心者でも理解しやすいように、成功例とエラーハンドリングの例を含みます。
22 */
23function demonstrateBackedEnumFromMethod(): void
24{
25    echo "--- BackedEnum::from() メソッドのデモンストレーション ---\n\n";
26
27    // 1. 存在するバッキング値から列挙型メンバーを取得する成功例
28    $existingValue = 'processing';
29    echo "既存のバッキング値 '{$existingValue}' から列挙型メンバーを取得します。\n";
30    try {
31        $processingStatus = OrderStatus::from($existingValue);
32        echo "成功: 取得したステータスは '{$processingStatus->name}' です。\n";
33        echo "そのバッキング値は '{$processingStatus->value}' です。\n";
34    } catch (ValueError $e) {
35        // このケースでは ValueError は発生しません。
36        echo "エラー: 予期せぬエラーが発生しました: " . $e->getMessage() . "\n";
37    }
38
39    echo "\n";
40
41    // 2. 存在しないバッキング値から列挙型メンバーを取得しようとする失敗例 (ValueError)
42    $nonExistentValue = 'shipped';
43    echo "存在しないバッキング値 '{$nonExistentValue}' から列挙型メンバーを取得しようとします。\n";
44    try {
45        // from() メソッドは、指定されたバッキング値に対応するメンバーがない場合、ValueError をスローします。
46        $shippedStatus = OrderStatus::from($nonExistentValue);
47        // 上の行でエラーがスローされるため、この行は実行されません。
48        echo "成功: 取得したステータスは '{$shippedStatus->name}' です。\n";
49    } catch (ValueError $e) {
50        // ここで ValueError をキャッチし、エラーを適切に処理します。
51        echo "エラー: '{$nonExistentValue}' に対応する列挙型メンバーが見つかりませんでした。\n";
52        echo "詳細: " . $e->getMessage() . "\n";
53    }
54
55    echo "\n";
56
57    // 3. 列挙型メンバーのプロパティ (name, value) の確認
58    echo "列挙型メンバーのプロパティの確認:\n";
59    $completedStatus = OrderStatus::Completed;
60    echo "OrderStatus::Completed の名前: " . $completedStatus->name . "\n";   // 列挙型メンバーの名前 ('Completed')
61    echo "OrderStatus::Completed のバッキング値: " . $completedStatus->value . "\n"; // 関連付けられたスカラー値 ('completed')
62}
63
64// 関数を呼び出してデモンストレーションを実行します。
65demonstrateBackedEnumFromMethod();
66

PHP 8.1で導入されたバッキング列挙型（Backed Enum）は、列挙型メンバーに特定のスカラー値（文字列または整数）を関連付ける機能です。OrderStatusのように、注文のステータスをコードと実値を紐付けて管理する際に役立ちます。

BackedEnum::from()メソッドは、このバッキング列挙型に定義されたスカラー値から、対応する列挙型メンバーを取得するために使用されます。引数$valueには、取得したいメンバーに紐付いているstring型またはint型のバッキング値を指定します。メソッドが成功すると、そのバッキング値に対応する列挙型メンバーのインスタンス（static）が戻り値として返されます。

例えば、'processing'というバッキング値を与えると、OrderStatus::Processingというメンバーが返されます。取得したメンバーからは、.nameプロパティでメンバー名（例: 'Processing'）、.valueプロパティで元のバッキング値（例: 'processing'）にアクセスできます。

重要な点として、もし指定したバッキング値に対応する列挙型メンバーが存在しない場合、from()メソッドはValueError例外をスローします。そのため、予期せぬエラーを防ぐためには、サンプルコードのようにtry-catchブロックでこの例外を適切に処理する必要があります。これにより、不正な値が入力された際のシステム停止を回避し、堅牢なプログラムを作成できます。