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

Copy
1<?php
2
3declare(strict_types=1); // 型厳格モードを有効にし、TypeErrorを明確にする
4
5/**
6 * 2つの整数を加算する関数
7 * この関数は引数として厳密にint型を期待します。
8 * 異なる型の引数が渡された場合、TypeErrorが発生します。
9 *
10 * @param int $a 最初の整数
11 * @param int $b 2番目の整数
12 * @return int 加算結果
13 */
14function addNumbers(int $a, int $b): int
15{
16    return $a + $b;
17}
18
19try {
20    // TypeErrorを意図的に発生させるために、int型を期待する$bにstring型を渡す
21    echo "不正な引数型でaddNumbers関数を呼び出します...\n";
22    addNumbers(10, 'twenty'); // ここでTypeErrorが発生する
23    echo "この行はTypeError発生のため実行されません。\n"; // エラー発生後のため到達しないコード
24} catch (TypeError $e) {
25    // TypeErrorを捕捉した場合の処理
26    echo "--- TypeErrorを捕捉しました ---\n";
27    echo "エラーメッセージ: " . $e->getMessage() . "\n";
28    echo "エラーが発生したファイル: " . $e->getFile() . " (行: " . $e->getLine() . ")\n";
29
30    // getTrace() メソッドでスタックトレース情報を取得する
31    // スタックトレースは、エラーが発生するまでの関数の呼び出し履歴を示します。
32    // 配列形式で、各要素が呼び出し元のファイル、行、関数名などの情報を含みます。
33    $trace = $e->getTrace();
34
35    echo "\n--- スタックトレース情報 (getTrace()) ---\n";
36    // var_dump は配列の構造と内容を詳細に表示するのに適しています
37    var_dump($trace);
38
39    echo "\nスタックトレースは、どの関数からどの関数が呼び出され、最終的にエラーが発生したかを\n";
40    echo "示すデバッグ情報として非常に役立ちます。\n";
41
42} catch (Exception $e) {
43    // その他の予期せぬ例外を捕捉する場合
44    echo "--- 予期せぬ例外を捕捉しました ---\n";
45    echo "エラーメッセージ: " . $e->getMessage() . "\n";
46}
47
48echo "\nスクリプトはエラー処理後に続行されます。\n";

PHP 8では、関数が期待する型と異なる引数が渡された場合にTypeErrorが発生します。TypeError::getTrace()メソッドは、このTypeErrorが発生するまでのプログラムの実行経路、つまり「スタックトレース」情報を取得するために利用されます。

このメソッドは引数を一切取りません。戻り値は配列（array）となり、エラー発生に至るまでの各関数の呼び出しに関する詳細な履歴情報を含んでいます。具体的には、どのファイルで、何行目で、どの関数が、どのような引数で呼び出されたかといった情報が、配列の各要素として格納されています。

サンプルコードでは、addNumbers関数が整数型を期待する引数に意図的に文字列を渡し、TypeErrorを発生させています。catchブロックでこのエラーを捕捉した後、$e->getTrace()を呼び出すことで、addNumbers関数が呼び出され、そこでTypeErrorが発生するまでの情報を配列として取得し、var_dumpでその内容を表示しています。

スタックトレース情報は、エラーの原因究明やデバッグ作業において、問題の発生箇所とその経緯を特定するための非常に重要な手がかりとなります。システム開発において、予期せぬエラーが発生した際に迅速に問題を解決するために、このメソッドの活用は不可欠です。

Copy
1<?php
2
3/**
4 * 型に関するエラーを意図的に発生させるための関数。
5 * この関数はint型を期待しますが、呼び出し側で異なる型を渡すことでTypeErrorを引き起こします。
6 *
7 * @param int $a 最初の数値
8 * @param int $b 2番目の数値
9 * @return int 合計
10 */
11function simulateTypeErrorOrigin(int $a, int $b): int
12{
13    // ここではエラーは発生しませんが、この関数がスタックトレースに含まれます。
14    return $a + $b;
15}
16
17/**
18 * TypeErrorの発生源となる呼び出しを行う関数。
19 *
20 * @param mixed $val_a 最初の値
21 * @param mixed $val_b 2番目の値
22 */
23function triggerTypeError(mixed $val_a, mixed $val_b): void
24{
25    // int型を期待するsimulateTypeErrorOrigin関数に、string型を渡すことでTypeErrorを発生させます。
26    // PHP 8では、このような型ヒントの不一致はTypeErrorとして扱われます。
27    simulateTypeErrorOrigin($val_a, $val_b);
28}
29
30// メインの処理
31try {
32    // わざと型に合わない引数を渡し、TypeErrorを発生させます。
33    triggerTypeError('hello', 10);
34} catch (TypeError $e) {
35    echo "--- TypeError が発生しました ---\n";
36    echo "メッセージ: " . $e->getMessage() . "\n";
37    echo "ファイル: " . $e->getFile() . "\n";
38    echo "行: " . $e->getLine() . "\n\n";
39
40    echo "--- getTrace() の出力 (配列形式) ---\n";
41    // getTrace() メソッドは、例外が発生するまでの呼び出しスタックを配列として返します。
42    // 各配列要素は、呼び出し元関数の情報（ファイル、行、関数名など）を含みます。
43    // これを解析して独自のログ形式にしたり、特定の情報を取り出したりする際に利用できます。
44    print_r($e->getTrace());
45    echo "\n";
46
47    echo "--- getTraceAsString() の出力 (文字列形式) ---\n";
48    // getTraceAsString() メソッドは、getTrace() で取得される情報を、
49    // 人間が読める形式のスタックトレース文字列として返します。
50    // これはデバッグ時に、どこでエラーが発生したかを素早く確認するためによく使用されます。
51    echo $e->getTraceAsString();
52    echo "\n";
53
54} catch (Exception $e) {
55    // TypeError以外の予期せぬ例外をキャッチする場合
56    echo "予期せぬ例外が発生しました: " . $e->getMessage() . "\n";
57}
58

PHPのこのサンプルコードは、意図的に型の不一致によるTypeErrorを発生させ、その例外情報を取得する方法を示しています。まず、simulateTypeErrorOrigin関数がint型を期待するところへ、triggerTypeError関数からstring型の引数が渡されることでTypeErrorが発生します。

try-catchブロックでTypeErrorを捕捉すると、例外オブジェクト$eからエラーメッセージ、ファイル名、行番号などの基本的な情報を取得できます。

$e->getTrace()メソッドは、引数なしで、例外が発生するまでの関数呼び出し履歴（スタックトレース）を詳細な配列形式で返します。この戻り値の配列には、各関数呼び出しのファイル名、行番号、関数名、引数などの情報が含まれており、プログラムの実行フローを深く分析したり、独自のログ形式で情報を記録したりする際に利用できます。

一方、$e->getTraceAsString()メソッドも引数なしで、getTrace()が提供する同じスタックトレース情報を、人間が読みやすい整形済みの文字列として返します。これはデバッグ時に、エラーがどの関数からどの関数を呼び出して発生したかを、コード全体を追いかけることなく迅速に確認するのに非常に役立ちます。この二つのメソッドは、エラーの原因究明やデバッグ作業において、それぞれ異なる形式で重要な情報を提供する役割を担っています。