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

getTraceメソッドの使い方について、初心者にもわかりやすく解説します。

作成日: 2025年09月11日更新日: 2025年12月19日

基本的な使い方

getTraceメソッドは、例外が発生した時点のバックトレース（関数の呼び出し履歴）を取得するメソッドです。OverflowExceptionのような例外がスローされた際にこのメソッドを呼び出すと、例外発生地点に至るまでにプログラムがどのような順序で関数やメソッドを呼び出してきたかの詳細な情報を得ることができます。この情報は、プログラムの不具合を修正するデバッグ作業において非常に重要であり、エラーの原因を特定するための強力な手がかりとなります。例えば、どの計算処理でオーバーフローが発生したのかを正確に追跡することが可能になります。getTraceメソッドが返す値は、トレース情報を格納した配列です。配列の各要素は、呼び出し階層の一段階分を表す連想配列となっており、その中にはファイル名、行番号、呼び出された関数名やクラス名、そして渡された引数などの情報が含まれています。このメソッドはOverflowExceptionクラスが親のExceptionクラスから継承している機能のため、PHPのほとんどの例外オブジェクトで共通して利用することができます。

構文(syntax)


1<?php
2
3try {
4    throw new OverflowException("An error occurred.");
5} catch (OverflowException $e) {
6    $trace = $e->getTrace();
7}

引数(parameters)

引数なし

引数はありません

戻り値(return)

array

例外発生時のコールスタック（処理の履歴）を配列形式で返します。

サンプルコード

PHPで例外のスタックトレースを取得する


1<?php
2
3declare(strict_types=1);
4
5/**
6 * スタックトレースを取得するサンプルコードを実行します。
7 * 
8 * この関数は、意図的に例外を発生させ、catchブロックで捕捉します。
9 * 捕捉した例外オブジェクトから getTraceAsString() メソッドを呼び出し、
10 * 例外が発生するまでの処理の呼び出し履歴（スタックトレース）を
11 * 文字列として取得し、コンソールに出力します。
12 */
13function showStackTraceExample(): void
14{
15    try {
16        // 第1階層の関数を呼び出す
17        firstLevelFunction();
18    } catch (OverflowException $e) {
19        // 発生したOverflowExceptionを捕捉する
20        echo "例外をキャッチしました。" . PHP_EOL;
21        echo "-----------------------------------------" . PHP_EOL;
22        echo "スタックトレース (getTraceAsString() の出力):" . PHP_EOL;
23
24        // getTraceAsString()メソッドを使い、スタックトレースを文字列として取得・出力する
25        // これにより、どこで例外がスローされたのか、そこに至るまでの関数呼び出しの経路がわかる
26        echo $e->getTraceAsString();
27
28        echo PHP_EOL . "-----------------------------------------" . PHP_EOL;
29    }
30}
31
32/**
33 * 第1階層の関数。内部で第2階層の関数を呼び出します。
34 */
35function firstLevelFunction(): void
36{
37    // スタックトレースに表示されるよう、別の関数を呼び出す
38    secondLevelFunction(10);
39}
40
41/**
42 * 第2階層の関数。ここで意図的に例外をスローします。
43 *
44 * @param int $value
45 */
46function secondLevelFunction(int $value): void
47{
48    // 何らかの処理の限界を超えたという想定で、OverflowExceptionをスローする
49    throw new OverflowException("処理能力の限界を超えました。値: {$value}");
50}
51
52// サンプルコードを実行
53showStackTraceExample();

このPHPサンプルコードは、例外が発生した際の処理の呼び出し履歴である「スタックトレース」を文字列として取得し、表示する方法を示します。プログラムのどこで予期せぬ問題が起きたのかを特定するデバッグ作業で非常に役立ちます。

コードの実行は showStackTraceExample 関数から始まります。この関数内の try ブロックで firstLevelFunction が呼び出され、さらにその内部で secondLevelFunction が呼び出されます。そして secondLevelFunction の中で、意図的に OverflowException という例外が発生させられます。

try ブロック内で発生した例外は、対になる catch ブロックで捕捉されます。ここでは、捕捉した例外オブジェクト（変数 $e）の getTraceAsString() メソッドを呼び出しています。このメソッドは引数を必要とせず、例外が発生した地点に至るまでの関数の呼び出し履歴を、人間が読みやすい形式の文字列として返します。

最後に、echo で getTraceAsString() が返した文字列を出力します。これにより、どのファイルの何行目でどの関数が呼び出され、最終的に例外が発生したのかという一連の流れがコンソールに表示され、エラーの原因を効率的に突き止めることができます。

getTraceAsString()メソッドは、例外発生箇所とそこまでの関数呼び出し履歴を文字列で取得できるため、デバッグに非常に役立ちます。注意点として、このメソッドが出力する情報には、サーバーのファイルパスといった機密情報が含まれる可能性があります。そのため、開発中のデバッグ目的での利用に留め、本番環境でユーザー画面に直接表示することは避けるべきです。本番環境では、スタックトレースはエラーログファイルに記録し、ユーザーには一般的なエラーメッセージを表示するようにしましょう。また、このメソッドは Throwable インターフェースを実装する全ての例外クラスで利用できます。