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

Copy
1<?php
2
3/**
4 * UnhandledMatchError を発生させる関数です。
5 * match 式がすべての可能な値を網羅していない場合に、このエラーがスローされます。
6 *
7 * @param int $status HTTPステータスコードのような数値
8 * @return string ステータスの説明
9 * @throws UnhandledMatchError $status が 0 または 1 以外の場合
10 */
11function getStatusDescription(int $status): string
12{
13    // この match 式は 0 と 1 のケースのみを処理します。
14    // それ以外の値（例: 200 や 404）が渡された場合、
15    // UnhandledMatchError がスローされます。
16    return match ($status) {
17        0 => "Success",
18        1 => "Failed",
19        // 他のステータスコードに対するケースが意図的に省略されています
20    };
21}
22
23// 例外処理のブロック
24try {
25    echo "--- 処理開始 ---\n";
26
27    // UnhandledMatchError を意図的に発生させる値を渡します
28    echo "getStatusDescription(200) を呼び出し中...\n";
29    $description = getStatusDescription(200); // ここで UnhandledMatchError が発生
30    echo "結果: " . $description . "\n";
31
32} catch (UnhandledMatchError $e) {
33    // UnhandledMatchError を捕捉します
34    echo "\n--- UnhandledMatchError を捕捉しました！ ---\n";
35    echo "エラーメッセージ: " . $e->getMessage() . "\n";
36    echo "発生ファイル: " . $e->getFile() . " (行: " . $e->getLine() . ")\n";
37
38    // getTrace() メソッドを使用して、例外が発生した時点のスタックトレースを取得します。
39    // スタックトレースは、プログラムがどの関数を、どのような順序で呼び出したかを示す情報です。
40    $trace = $e->getTrace();
41
42    echo "\n--- スタックトレース (getTrace() の出力) ---\n";
43    // 取得したスタックトレースは配列形式で、print_r で内容を確認できます。
44    // 各要素は、関数名、ファイル名、行番号などの呼び出し情報を含みます。
45    print_r($trace);
46
47} catch (Throwable $e) {
48    // UnhandledMatchError 以外の予期せぬエラーを捕捉します
49    echo "\n--- 予期せぬエラーを捕捉しました！ ---\n";
50    echo "エラータイプ: " . get_class($e) . "\n";
51    echo "メッセージ: " . $e->getMessage() . "\n";
52}
53
54echo "\n--- 処理終了 ---\n";
55

PHP 8のUnhandledMatchError::getTrace()メソッドは、match式がすべての可能な値を網羅していない場合に発生するUnhandledMatchErrorオブジェクトから、例外が発生した時点のプログラムの実行履歴（スタックトレース）を取得するために使用されます。このメソッドは引数を一切取らず、例外がどの関数からどの関数を呼び出して発生したかを示す詳細な情報が格納された配列を戻り値として返します。

戻り値の配列には、関数名、引数、ファイル名、行番号など、例外発生までの呼び出し経路に関する情報が要素として含まれます。サンプルコードでは、意図的にUnhandledMatchErrorを発生させ、catchブロックでそのエラーを捕捉しています。その後、捕捉したエラーオブジェクトに対してgetTrace()メソッドを呼び出し、取得したスタックトレースをprint_rで表示することで、エラーがgetStatusDescription関数内で、どの行で発生したかといった具体的なデバッグ情報を確認しています。このスタックトレースは、エラーの原因究明や修正作業を進める上で非常に重要な手がかりとなります。

Copy
1<?php
2
3/**
4 * UnhandledMatchError を意図的に発生させる関数。
5 *
6 * PHP 8 の `match` 式を使用し、指定された値に対応するケースがない場合に
7 * `UnhandledMatchError` がスローされることを示します。
8 *
9 * @param string $fruitName 処理する果物の名前
10 * @return string 果物の説明
11 */
12function processFruit(string $fruitName): string
13{
14    // match 式は、すべての可能な値が網羅されていない場合に UnhandledMatchError をスローします。
15    // この例では 'orange' のケースが意図的に欠落しています。
16    return match ($fruitName) {
17        'apple' => 'これはリンゴです。',
18        'banana' => 'これはバナナです。',
19        // 'orange' がここにないため、'orange' が渡されると UnhandledMatchError が発生します。
20    };
21}
22
23/**
24 * メイン処理。
25 *
26 * UnhandledMatchError を捕捉し、そのスタックトレース情報を取得して表示します。
27 */
28function main(): void
29{
30    echo "--- UnhandledMatchError の発生と捕捉の例 ---\n\n";
31
32    try {
33        // UnhandledMatchError を発生させるために、`match` 式で処理されない値を渡します。
34        echo "processFruit('orange') を呼び出しています...\n";
35        echo processFruit('orange') . "\n"; // ここで UnhandledMatchError がスローされます
36    } catch (UnhandledMatchError $e) {
37        echo "\n### UnhandledMatchError を捕捉しました！ ###\n";
38        echo "エラーメッセージ: " . $e->getMessage() . "\n";
39        echo "エラーが発生したファイル: " . $e->getFile() . "\n";
40        echo "エラーが発生した行: " . $e->getLine() . "\n\n";
41
42        // UnhandledMatchError::getTrace() の使用例
43        // スタックトレースを配列形式で取得します。
44        echo "--- getTrace() の出力 (配列形式) ---\n";
45        print_r($e->getTrace());
46        echo "\n";
47
48        // エラー処理のキーワードに関連する getTraceAsString() の使用例
49        // スタックトレースを人間が読みやすい文字列形式で取得します。
50        echo "--- getTraceAsString() の出力 (文字列形式) ---\n";
51        echo $e->getTraceAsString();
52        echo "\n";
53    } catch (Throwable $e) {
54        // その他の予期せぬエラーが発生した場合の汎用的な捕捉
55        echo "\n### 予期せぬエラーを捕捉しました！ ###\n";
56        echo "種類: " . get_class($e) . "\n";
57        echo "メッセージ: " . $e->getMessage() . "\n";
58        echo $e->getTraceAsString();
59    }
60
61    echo "\n--- 処理が終了しました ---\n";
62}
63
64// スクリプトの実行
65main();
66
67?>

UnhandledMatchError::getTrace()は、PHP 8で導入されたmatch式において、指定された値がどのケースにも一致しなかった場合に発生するUnhandledMatchErrorというエラー（例外）の詳細な情報を取得するためのメソッドです。このメソッドは引数を取らず、エラーが発生した時点までの関数呼び出し履歴（スタックトレース）を配列形式で返します。

サンプルコードでは、processFruit関数内でmatch式に定義されていない'orange'という値を渡し、UnhandledMatchErrorを意図的に発生させています。main関数内のtry-catchブロックでこのエラーを捕捉した後、$e->getTrace()を呼び出すことで、エラー発生に至るまでの具体的な処理の流れを配列として確認できます。この配列の各要素には、エラーが発生したファイル名、行番号、呼び出された関数名などが詳細に含まれており、エラーの原因特定に役立ちます。

また、キーワードにあるgetTraceAsString()メソッドも、getTrace()と同じスタックトレース情報を返しますが、こちらは人間が読みやすい文字列形式で整形されたデータを出力します。getTrace()がプログラミングによる詳細な解析やログ処理に適しているのに対し、getTraceAsString()はデバッグ時の画面表示やログ出力など、直接内容を確認する際に非常に便利です。これらのメソッドを使いこなすことで、プログラムの不具合箇所を効率的に特定し、修正することができます。

Copy
1<?php
2
3/**
4 * この関数は、意図的に UnhandledMatchError を発生させます。
5 * match 式がすべての可能性を網羅していない場合に発生するエラーです。
6 *
7 * @param int $value 判定する値
8 */
9function triggerUnhandledMatchError(int $value): void
10{
11    // match 式は PHP 8 以降で導入されました。
12    // $value が 1 または 2 の場合は処理されますが、
13    // 他の値（例: 3）の場合は UnhandledMatchError が発生します。
14    match ($value) {
15        1 => print "値は1です。\n",
16        2 => print "値は2です。\n",
17        // デフォルトケース (_ => ...) がないため、他の値でエラーが発生します。
18    };
19}
20
21// UnhandledMatchError を捕捉するために try-catch ブロックを使用します。
22try {
23    // 意図的に UnhandledMatchError が発生するような値を渡します。
24    triggerUnhandledMatchError(3);
25} catch (UnhandledMatchError $e) {
26    // エラーが捕捉されたことを表示します。
27    echo "UnhandledMatchError が捕捉されました！\n\n";
28
29    // --- getTrace() の使用例 ---
30    // getTrace() メソッドは、エラーが発生した時点のスタックトレースを
31    // 配列（array）形式で返します。
32    // 各要素は、呼び出し元ファイル、行番号、関数名などの情報を持つ配列です。
33    echo "--- getTrace() で取得したスタックトレース (配列形式) ---\n";
34    print_r($e->getTrace());
35    echo "\n";
36
37    // --- getTraceAsString() の使用例 ---
38    // キーワードに関連する getTraceAsString() メソッドも紹介します。
39    // このメソッドは、スタックトレースを人間が読みやすい文字列形式で返します。
40    // getTrace() で得られる情報を整形して表示する際に便利です。
41    echo "--- getTraceAsString() で取得したスタックトレース (文字列形式) ---\n";
42    echo $e->getTraceAsString();
43}
44
45?>

このPHPコードは、PHP 8で導入されたUnhandledMatchErrorというエラーの捕捉と、そのエラー情報を取得する方法を示しています。UnhandledMatchErrorは、match式が評価するすべてのケースを網羅していない場合に発生するエラーです。

サンプルコードでは、triggerUnhandledMatchError関数で意図的にこのエラーを発生させ、try-catchブロックでUnhandledMatchErrorを捕捉しています。エラーが捕捉された後、$eというエラーオブジェクトから呼び出せるgetTrace()メソッドについて解説します。

getTrace()メソッドは引数を取らず、エラーが発生した時点の関数の呼び出し履歴、つまり「スタックトレース」を配列（array）形式で返します。この配列には、エラーが発生するまでの各ステップにおけるファイル名、行番号、関数名などの詳細な情報が含まれており、エラーの原因を特定する際に非常に役立ちます。

また、関連するgetTraceAsString()メソッドも紹介しています。このメソッドもスタックトレースを返しますが、getTrace()がプログラムで処理しやすい配列形式であるのに対し、getTraceAsString()は人間が読みやすい整形された文字列形式で返します。デバッグ時にスタックトレースを直接表示する際に便利です。