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

Copy
1<?php
2
3/**
4 * PHP 8.1以降で利用可能なBacked Enumの例。
5 * 各Enumケースは、一意な文字列値を持ちます。
6 * これは、システム内で役割を定義する際などに役立ちます。
7 */
8enum UserRole: string
9{
10    case Administrator = 'admin';
11    case Editor = 'editor';
12    case Viewer = 'viewer';
13}
14
15/**
16 * `UserRole::tryFrom()` メソッドの使用例を示します。
17 * このメソッドは、与えられたバックアップ値に対応するEnumケースを返します。
18 * 対応するケースが見つからない場合は `null` を返します。
19 * これは、外部からの入力値を安全にEnumに変換する際に非常に有用です。
20 */
21function demonstrateEnumTryFromNull(): void
22{
23    echo "--- 有効なバックアップ値からEnumケースを取得する例 ---\n";
24    // 'admin' は UserRole::Administrator に対応する文字列です。
25    // tryFrom() は対応するEnumケースのインスタンスを返します。
26    $adminRole = UserRole::tryFrom('admin');
27    var_dump($adminRole);
28
29    echo "\n--- 存在しないバックアップ値からEnumケースを取得する例 ---\n";
30    // 'guest' は UserRole Enumのどのケースにも対応しません。
31    // この場合、`tryFrom()` メソッドは `null` を返します。
32    $guestRole = UserRole::tryFrom('guest');
33    var_dump($guestRole);
34
35    // `null` が返された場合の処理例
36    if ($guestRole === null) {
37        echo "注意: 'guest' に対応するユーザーロールEnumケースは見つかりませんでした。\n";
38        // ここでデフォルト値を設定したり、エラー処理を行うことができます。
39        // 例として、デフォルトの役割を Viewer に設定します。
40        $currentUserRole = UserRole::Viewer;
41        echo "代わりにデフォルトの役割として '" . $currentUserRole->value . "' を設定しました。\n";
42    }
43
44    echo "\n--- 型が異なるバックアップ値の場合 (エラーは発生しないが、nullが返る) ---\n";
45    // UserRoleはstring型のバックアップ値を持つEnumです。
46    // int型の値を渡した場合、一致するEnumケースがないため、エラーにはならずnullが返ります。
47    $numericRole = UserRole::tryFrom(123);
48    var_dump($numericRole);
49    if ($numericRole === null) {
50        echo "注意: 数値 '123' は文字列ベースのUserRole Enumとは一致しませんでした。\n";
51    }
52}
53
54// 上記の関数を実行して、`tryFrom` の動作を確認します。
55demonstrateEnumTryFromNull();

PHP 8.1で導入されたBacked Enum（バックアップEnum）において、tryFromメソッドは、与えられたバックアップ値（文字列または整数）に対応するEnumケースのインスタンスを安全に取得するために使用されます。このメソッドは、引数として指定されたstring|int $valueがEnumケースのバックアップ値と一致する場合、対応するEnumケースのインスタンス（static型）を返します。

もし、指定された$valueに対応するEnumケースが見つからない場合、または$valueの型がEnumのバックアップ値の型と異なる場合でも、エラーを発生させずにnullを返します。これにより、外部からの不確かな入力値をEnumに変換する際に、プログラムが中断することなく、nullチェックを行うことで柔軟なエラーハンドリングやデフォルト値の設定が可能になります。例えば、サンプルコードでは存在しないロール名や型不一致の数値が渡された際にnullが返され、その後の処理でデフォルトの役割を設定するなどの対応が示されています。

Copy
1<?php
2
3/**
4 * PropertyHookType enumは、プロパティのフックの種類を表します。
5 * PHP 8.1で導入された、文字列でバックされたEnumとして定義されています。
6 */
7enum PropertyHookType: string
8{
9    case BEFORE_SET = 'before_set';
10    case AFTER_SET = 'after_set';
11    case ON_GET = 'on_get';
12}
13
14/**
15 * 指定された入力値を PropertyHookType enumケースに変換を試みます。
16 * PropertyHookType::tryFrom() の使用方法を示します。
17 *
18 * @param string|int $inputValue 変換を試みる生の値。
19 * @return void
20 */
21function demonstrateTryFromPropertyHookType(string|int $inputValue): void
22{
23    // PropertyHookType::tryFrom() は、バッキング値からEnumインスタンスの作成を試みます。
24    // マッチするEnumケースが見つからない場合、例外をスローする代わりにnullを返します。
25    $hookType = PropertyHookType::tryFrom($inputValue);
26
27    if ($hookType === null) {
28        echo "入力値 '{$inputValue}' に対応する PropertyHookType が見つかりませんでした。\n";
29    } else {
30        echo "入力値 '{$inputValue}' は PropertyHookType::{$hookType->name} に対応します (バッキング値: '{$hookType->value}')。\n";
31    }
32}
33
34// --- PropertyHookType::tryFrom() の使用例 ---
35
36// 存在するバッキング値 (文字列) の例
37demonstrateTryFromPropertyHookType('before_set');
38demonstrateTryFromPropertyHookType('on_get');
39
40echo "\n";
41
42// 存在しないバッキング値 (文字列) の例
43demonstrateTryFromPropertyHookType('invalid_hook_type');
44
45// このEnumは文字列でバックされているため、整数値はnullを返します。
46demonstrateTryFromPropertyHookType(123);
47
48?>

PHP 8.1で導入されたEnum（列挙型）は、特定の選択肢を明確に定義する際に役立ちます。PropertyHookTypeは、プロパティ操作のフックの種類を定義するために用いられる、文字列でバックされたEnumです。

PropertyHookType::tryFrom()メソッドは、このEnumのバッキング値（'before_set'などの文字列）から、対応するEnumのインスタンスを安全に取得するために使用されます。引数$valueには、変換を試みる文字列または整数を渡します。

このメソッドの大きな特徴は、戻り値の挙動です。もし渡された$valueに対応するEnumケースが見つかった場合、そのPropertyHookTypeのインスタンスを返します。しかし、対応するケースが存在しない場合は、例外を発生させることなくnullを返します。これにより、Enumの変換処理を柔軟かつエラーを意識せずに記述することができます。

例えば、サンプルコードでは、存在するバッキング値である'before_set'や'on_get'を渡すと、それぞれPropertyHookType::BEFORE_SETやPropertyHookType::ON_GETのインスタンスが取得されます。一方、'invalid_hook_type'のような存在しない値や、このEnumが文字列でバックされているにもかかわらず123のような整数を渡した場合は、nullが返されるため、プログラムはエラーで停止することなく処理を続行できます。これは、外部からの入力値など、変換が成功するか不確かである場合に特に有用な機能です。