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

Copy
1<?php
2
3/**
4 * Throwable::getTrace メソッドの使用例。
5 * 例外発生時のスタックトレース情報を取得し、その内容を表示します。
6 *
7 * この関数内で複数の関数を呼び出すことで、スタックトレースに深みを持たせ、
8 * getTrace() メソッドがどのように呼び出し履歴を返すかを示します。
9 */
10function demonstrateGetTraceUsage(): void
11{
12    try {
13        // 例外を発生させる可能性のある処理を開始します。
14        // 複数の関数を呼び出すことで、スタックトレースがより詳細になります。
15        callFunctionA();
16    } catch (\Throwable $e) {
17        // 例外が捕捉されたことを表示します。
18        echo "--- 捕捉された例外情報 ---\n";
19        echo "メッセージ: " . $e->getMessage() . "\n";
20        echo "発生ファイル: " . $e->getFile() . " (行: " . $e->getLine() . ")\n";
21        echo "--------------------------\n\n";
22
23        // Throwable::getTrace() メソッドでスタックトレース情報を取得します。
24        // これは、例外が発生するまでに実行された関数やメソッドの呼び出し履歴を
25        // 配列形式で返します。
26        $trace = $e->getTrace();
27
28        echo "--- スタックトレース情報 (Throwable::getTrace() の結果) ---\n";
29        // 取得したトレース情報を整形して表示します。
30        // 各配列要素は、呼び出し元に関する情報（関数名、ファイル名、行番号など）を
31        // 持つ連想配列です。
32        print_r($trace);
33        echo "------------------------------------------------------------\n";
34    }
35}
36
37/**
38 * 呼び出し階層の最初の関数。
39 * 次の関数を呼び出します。
40 */
41function callFunctionA(): void
42{
43    callFunctionB();
44}
45
46/**
47 * 呼び出し階層の二番目の関数。
48 * ここで意図的に例外をスローします。
49 */
50function callFunctionB(): void
51{
52    // ここで意図的にExceptionをスローし、スタックトレースを生成させます。
53    throw new \Exception("データ処理中に予期せぬエラーが発生しました。");
54}
55
56// サンプルコードを実行します。
57demonstrateGetTraceUsage();

PHP 8のThrowable::getTraceメソッドは、プログラムの実行中に例外やエラーが発生した際、その問題が発生するまでの「呼び出し履歴」、つまりスタックトレースの情報を取得するための機能です。このメソッドは引数を一切取らず、例外がスローされるまでに実行された関数やメソッドの呼び出し情報が詳細に格納された配列を返します。配列の各要素は連想配列となっており、呼び出しが行われたファイル名、行番号、関数名、引数などの情報を含みます。

サンプルコードでは、demonstrateGetTraceUsage関数が複数の関数を順に呼び出し、最終的にcallFunctionB関数で意図的に例外をスローしています。この例外がtry-catchブロックで捕捉されると、$e->getTrace()メソッドが呼び出され、demonstrateGetTraceUsageからcallFunctionA、そしてcallFunctionBに至るまでの一連の呼び出し経路が配列として取得されます。この取得されたスタックトレース情報を表示することで、例外発生時にプログラムがどのような順序で実行されていたかを明確に把握でき、問題の原因究明やデバッグ作業に非常に役立ちます。

Copy
1<?php
2
3/**
4 * Throwable::getTrace() メソッドが返す配列を、
5 * 人間が読みやすいスタックトレース文字列に整形します。
6 *
7 * @param Throwable $exception 例外オブジェクト
8 * @return string 整形されたスタックトレース文字列
9 */
10function formatTraceAsString(Throwable $exception): string
11{
12    $trace = $exception->getTrace();
13    $formattedTrace = [];
14    $traceIndex = 0;
15
16    // 各スタックフレームの情報を整形して追加
17    foreach ($trace as $frame) {
18        $file = $frame['file'] ?? 'n/a';
19        $line = $frame['line'] ?? 'n/a';
20        $function = $frame['function'] ?? 'n/a';
21        $class = $frame['class'] ?? '';
22        $type = $frame['type'] ?? ''; // メソッドの種類 (例: '->' または '::')
23
24        // 引数を文字列に変換する内部ヘルパー関数
25        $formatArgs = function (array $args): string {
26            $stringArgs = [];
27            foreach ($args as $arg) {
28                if (is_object($arg)) {
29                    $stringArgs[] = 'object(' . get_class($arg) . ')';
30                } elseif (is_array($arg)) {
31                    $stringArgs[] = 'array'; // 配列の中身は省略して表示
32                } elseif (is_string($arg)) {
33                    $stringArgs[] = "'" . (strlen($arg) > 20 ? substr($arg, 0, 17) . '...' : $arg) . "'";
34                } elseif (is_null($arg)) {
35                    $stringArgs[] = 'NULL';
36                } elseif (is_bool($arg)) {
37                    $stringArgs[] = $arg ? 'true' : 'false';
38                } elseif (is_numeric($arg)) {
39                    $stringArgs[] = (string) $arg;
40                } else {
41                    $stringArgs[] = gettype($arg);
42                }
43            }
44            return implode(', ', $stringArgs);
45        };
46
47        $call = $class . $type . $function . '(' . $formatArgs($frame['args'] ?? []) . ')';
48
49        $formattedTrace[] = sprintf("#%d %s(%s): %s",
50            $traceIndex++,
51            $file,
52            $line,
53            $call
54        );
55    }
56
57    // 例外自身のファイル、行、メッセージはgetTrace()の結果には含まれないため、個別に追加
58    $formattedTrace[] = sprintf("#%d %s(%s): %s",
59        $traceIndex,
60        $exception->getFile(),
61        $exception->getLine(),
62        $exception->getMessage()
63    );
64
65    return implode("\n", $formattedTrace);
66}
67
68// --- サンプルコードの実行部分 ---
69
70// 例外を発生させるための関数群
71function performDivision(int $numerator, int $denominator): float
72{
73    if ($denominator === 0) {
74        // 0で割ろうとした場合に例外をスロー
75        throw new InvalidArgumentException("Division by zero is not allowed.");
76    }
77    return $numerator / $denominator;
78}
79
80function calculateAverage(int $total, int $count): float
81{
82    // さらに別の関数を呼び出す
83    return performDivision($total, $count);
84}
85
86function processData(array $data): string
87{
88    // ここで意図的にエラーを発生させるために0を渡す
89    $result = calculateAverage($data[0] ?? 0, $data[1] ?? 0);
90    return "Result: " . $result;
91}
92
93// メインの実行ブロック
94try {
95    echo processData([100, 0]); // 意図的にエラーが発生するデータで関数を呼び出す
96} catch (Throwable $e) {
97    // 捕捉した例外からスタックトレースを取得し、文字列として整形して表示
98    echo "--- 例外が発生しました ---\n";
99    echo "エラーメッセージ: " . $e->getMessage() . "\n";
100    echo "ファイル: " . $e->getFile() . "\n";
101    echo "行: " . $e->getLine() . "\n";
102    echo "\n--- スタックトレース (整形済み) ---\n";
103    echo formatTraceAsString($e) . "\n"; // ここで整形されたスタックトレースを出力
104    echo "-----------------------------------\n";
105}

PHP 8のThrowable::getTrace()メソッドは、例外が発生した際に、その例外がどの関数からどの関数へと伝わって発生したかという「呼び出し履歴」、いわゆるスタックトレースの情報を配列として取得します。この配列は、エラーの原因を特定するのに役立つファイル名、行番号、関数名などの詳細な情報を含んでいます。

サンプルコードのformatTraceAsString関数は、このgetTrace()メソッドが返す配列を、人間が読みやすい形式の一連の文字列（スタックトレース文字列）に整形するために作成されています。この関数は、引数として発生したThrowable型の例外オブジェクトを受け取ります。そして、戻り値として、整形されたスタックトレースの文字列を返します。 関数内部では、getTrace()から得られた各呼び出しフレーム（情報の塊）を一つずつ処理し、ファイル名、行番号、関数名、クラス名、引数などを結合して一行ずつの情報を作成しています。特に引数については、その型（オブジェクト、配列、文字列など）に応じて見やすく変換する工夫がされています。最後に、例外自体のメッセージや発生場所の情報も加えて、全体を改行でつないだ一つの文字列として完成させます。

実行例では、意図的にエラーを起こすことで例外を発生させ、try-catch文でそれを捕捉しています。捕捉した例外オブジェクトをformatTraceAsString関数に渡すことで、複雑な配列情報を読みやすいスタックトレース文字列として出力し、エラーの追跡に利用できることを示しています。