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

Copy
1<?php
2
3/**
4 * BackedEnum を実装した列挙型を定義します。
5 * 各ケースには整数値の「バッキング値」が関連付けられています。
6 */
7enum StatusCode: int
8{
9    case OK = 200;
10    case Created = 201;
11    case NotFound = 404;
12    case InternalServerError = 500;
13}
14
15/**
16 * BackedEnum::tryFrom メソッドの動作を示す関数です。
17 * このメソッドは、指定されたバッキング値に対応する列挙ケースを返します。
18 * 対応するケースが存在しない場合は null を返します。
19 */
20function demonstrateTryFrom(): void
21{
22    echo "--- BackedEnum::tryFrom メソッドの動作デモンストレーション ---" . PHP_EOL;
23    echo "このメソッドは、対応するケースが見つからない場合に null を返します。" . PHP_EOL . PHP_EOL;
24
25    // 1. 存在するバッキング値 (200) で tryFrom を呼び出します。
26    // この場合、StatusCode::OK ケースが返されるはずです。
27    $existingValue = 200;
28    $caseForExistingValue = StatusCode::tryFrom($existingValue);
29
30    if ($caseForExistingValue !== null) {
31        echo "値 '{$existingValue}' に対応するケース: " . $caseForExistingValue->name . " (バッキング値: " . $caseForExistingValue->value . ")" . PHP_EOL;
32    } else {
33        // このパスは、存在する値の場合は実行されません。
34        echo "値 '{$existingValue}' に対応するケースは見つかりませんでした。" . PHP_EOL;
35    }
36    echo PHP_EOL;
37
38    // 2. 存在しないバッキング値 (403) で tryFrom を呼び出します。
39    // この場合、対応するケースがないため null が返されるはずです。
40    $nonExistingValue = 403; // HTTP 403 Forbidden に対応するケースは StatusCode 列挙型には定義されていません。
41    $caseForNonExistingValue = StatusCode::tryFrom($nonExistingValue);
42
43    if ($caseForNonExistingValue !== null) {
44        // このパスは、存在しない値の場合は実行されません。
45        echo "値 '{$nonExistingValue}' に対応するケース: " . $caseForNonExistingValue->name . " (バッキング値: " . $caseForNonExistingValue->value . ")" . PHP_EOL;
46    } else {
47        // null が返されるため、このパスが実行されます。
48        echo "値 '{$nonExistingValue}' に対応するケースは見つかりませんでした。-> null が返されました。" . PHP_EOL;
49    }
50    echo PHP_EOL;
51
52    // 3. 別の存在するバッキング値 (500) で tryFrom を呼び出します。
53    $anotherExistingValue = 500;
54    $caseForAnotherExistingValue = StatusCode::tryFrom($anotherExistingValue);
55
56    if ($caseForAnotherExistingValue !== null) {
57        echo "値 '{$anotherExistingValue}' に対応するケース: " . $caseForAnotherExistingValue->name . " (バッキング値: " . $caseForAnotherExistingValue->value . ")" . PHP_EOL;
58    } else {
59        echo "値 '{$anotherExistingValue}' に対応するケースは見つかりませんでした。" . PHP_EOL;
60    }
61    echo PHP_EOL;
62
63    echo "--- デモンストレーション終了 ---" . PHP_EOL;
64}
65
66// デモンストレーション関数を実行します。
67demonstrateTryFrom();

PHPのBackedEnum::tryFromメソッドは、バッキング値を持つ列挙型（BackedEnum）において、指定されたバッキング値に対応する列挙ケースを安全に取得するために使用されます。このメソッドは、引数として検索したいバッキング値（整数または文字列）を受け取ります。指定されたバッキング値に一致する列挙ケースが定義されていれば、そのケースのインスタンスが戻り値として返されます。しかし、もし一致するケースが見つからない場合、このメソッドはnullを返します。これにより、対応するケースがない場合でもプログラムが例外を発生させることなく、処理を継続できるため、エラーハンドリングを簡潔に記述できる利点があります。サンプルコードでは、存在するバッキング値（200, 500）に対しては適切な列挙ケースが取得され、存在しないバッキング値（403）に対してはnullが返される様子が具体的に示されています。

Copy
1<?php
2
3// PHP 8.1以降で利用可能なBackedEnumを定義します。
4// BackedEnumは、Enumの各ケースにスカラー値（文字列または整数）を関連付けることができます。
5enum UserStatus: string
6{
7    case Active = 'active';
8    case Inactive = 'inactive';
9    case Pending = 'pending';
10    case Deleted = 'deleted';
11}
12
13echo "--- BackedEnum::tryFrom() の使用例 ---" . PHP_EOL;
14
15// tryFrom() メソッドは、指定されたバッキング値に対応するEnumケースがあればそのインスタンスを返します。
16// 対応するケースが見つからない場合は、エラーを発生させずに null を返します。
17// これは、存在しない値でEnumを作成しようとした場合にプログラムが中断するのを防ぐのに役立ちます。
18
19// 1. 有効なバッキング値の場合
20// 'active' は UserStatus::Active に対応するため、UserStatus::Active のインスタンスが返されます。
21$activeStatus = UserStatus::tryFrom('active');
22echo "UserStatus::tryFrom('active') の結果: ";
23if ($activeStatus !== null) {
24    echo "ケース名: " . $activeStatus->name . ", バッキング値: " . $activeStatus->value . PHP_EOL;
25} else {
26    echo "null (見つかりませんでした)" . PHP_EOL;
27}
28
29// 2. 別の有効なバッキング値の場合
30// 'pending' は UserStatus::Pending に対応するため、UserStatus::Pending のインスタンスが返されます。
31$pendingStatus = UserStatus::tryFrom('pending');
32echo "UserStatus::tryFrom('pending') の結果: ";
33if ($pendingStatus !== null) {
34    echo "ケース名: " . $pendingStatus->name . ", バッキング値: " . $pendingStatus->value . PHP_EOL;
35} else {
36    echo "null (見つかりませんでした)" . PHP_EOL;
37}
38
39// 3. 無効なバッキング値の場合
40// 'unknown' はどの UserStatus ケースにも対応しないため、null が返されます。
41$unknownStatus = UserStatus::tryFrom('unknown');
42echo "UserStatus::tryFrom('unknown') の結果: ";
43if ($unknownStatus !== null) {
44    echo "ケース名: " . $unknownStatus->name . ", バッキング値: " . $unknownStatus->value . PHP_EOL;
45} else {
46    echo "null (見つかりませんでした)" . PHP_EOL;
47}
48
49echo PHP_EOL . "--- tryFrom() の戻り値の確認 ---" . PHP_EOL;
50
51// tryFrom() の結果は null である可能性があるため、通常は if 文などで確認してから使用します。
52$inputStatus = 'inactive'; // 例えば、ユーザーからの入力値
53$statusObject = UserStatus::tryFrom($inputStatus);
54
55if ($statusObject !== null) {
56    echo "入力値 '" . $inputStatus . "' に対応するステータスが取得できました: " . $statusObject->name . PHP_EOL;
57    // 取得したEnumケースを使って処理を続行できます
58    if ($statusObject === UserStatus::Inactive) {
59        echo "ユーザーは現在非アクティブです。" . PHP_EOL;
60    }
61} else {
62    echo "入力値 '" . $inputStatus . "' は無効なステータスです。" . PHP_EOL;
63}
64
65echo PHP_EOL;
66
67// 存在しない値の例
68$nonExistentInput = 'archived';
69$nonExistentStatus = UserStatus::tryFrom($nonExistentInput);
70
71if ($nonExistentStatus !== null) {
72    echo "入力値 '" . $nonExistentInput . "' に対応するステータスが取得できました: " . $nonExistentStatus->name . PHP_EOL;
73} else {
74    echo "入力値 '" . $nonExistentInput . "' は無効なステータスです。" . PHP_EOL;
75}

PHP 8.1で導入されたBackedEnumは、Enumの各ケースに文字列や整数といった具体的な値（バッキング値）を関連付けることができる機能です。BackedEnum::tryFrom()メソッドは、このバッキング値を使って対応するEnumケースのインスタンスを安全に取得するために使われます。

このメソッドは、引数として検索したいバッキング値（stringまたはint）を受け取ります。指定されたバッキング値に一致するEnumケースが存在する場合、そのケースのインスタンスを戻り値として返します。例えば、UserStatus::tryFrom('active')のように呼び出すと、定義されたUserStatus::Activeケースのインスタンスが得られます。

一方、指定されたバッキング値に対応するEnumケースが存在しない場合、tryFrom()メソッドはエラー（例外）を発生させることなく、安全にnullを返します。これにより、ユーザーからの入力など、存在しない可能性のある値に対して、プログラムが予期せず中断することを防ぐことができます。

戻り値は?staticと示されており、Enumケースのインスタンスかnullのどちらかが返されることを意味します。そのため、通常はif文などでnullかどうかを確認してから、取得したEnumケースを使って処理を進めるのが良いプラクティスです。これは、無効な入力値に対して堅牢なシステムを構築する上で非常に役立ちます。