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

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

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

基本的な使い方

getTraceメソッドは、例外がスローされた時点のバックトレース（スタックトレース）を取得するために実行するメソッドです。このメソッドは、UnexpectedValueExceptionクラスがその親クラスであるExceptionクラスから継承しています。UnexpectedValueExceptionは、変数の値が期待される値のセットと一致しない、予期しない値であった場合に発生する例外です。getTraceメソッドを呼び出すと、例外が発生した箇所からプログラムの実行開始点に至るまで、どのような関数やメソッドがどのような順序で呼び出されたかの履歴が配列として返されます。返される配列の各要素は、呼び出しスタックの各ステップを表す連想配列となっており、ファイル名、行番号、関数名、クラス名、そして関数に渡された引数といった詳細な情報が含まれています。この情報を利用することで、開発者は予期しない値がプログラムのどの経路をたどって渡されてきたのかを正確に追跡でき、問題の原因を効率的に特定するための重要な手がかりを得ることができます。したがって、このメソッドはデバッグ作業において非常に役立ちます。

構文(syntax)


1<?php
2try {
3    throw new UnexpectedValueException("予期しない値が検出されました。");
4} catch (UnexpectedValueException $e) {
5    $stackTrace = $e->getTrace();
6}

引数(parameters)

引数なし

引数はありません

戻り値(return)

array

例外発生時のトレース情報（スタックトレース）を配列形式で返します。この配列には、例外が発生した場所や、そこに至るまでの関数の呼び出し履歴などが含まれます。

サンプルコード

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


1<?php
2
3/**
4 * 意図的に例外を発生させ、スタックトレースを文字列で取得するサンプルクラス
5 */
6class ExceptionTraceExample
7{
8    /**
9     * 処理を実行し、例外を捕捉してスタックトレースを出力します。
10     */
11    public function run(): void
12    {
13        try {
14            // 例外が発生する可能性のあるメソッドを呼び出します。
15            $this->methodA();
16        } catch (UnexpectedValueException $e) {
17            // catchブロックで例外オブジェクトを捕捉します。
18            echo "--- 例外情報 ---\n";
19            echo "メッセージ: " . $e->getMessage() . "\n\n";
20
21            // getTraceAsString()メソッドを使い、スタックトレースを文字列として取得します。
22            // これにより、例外が発生するまでの関数の呼び出し履歴を追跡できます。
23            $traceString = $e->getTraceAsString();
24
25            echo "--- スタックトレース (getTraceAsString) ---\n";
26            echo $traceString;
27        }
28    }
29
30    /**
31     * 別のメソッドを呼び出す中間メソッド1
32     */
33    private function methodA(): void
34    {
35        $this->methodB('test_data', 123);
36    }
37
38    /**
39     * さらに別のメソッドを呼び出す中間メソッド2
40     *
41     * @param string $param1
42     * @param int $param2
43     */
44    private function methodB(string $param1, int $param2): void
45    {
46        $this->throwException();
47    }
48
49    /**
50     * 意図的にUnexpectedValueExceptionをスローするメソッド
51     *
52     * @throws UnexpectedValueException
53     */
54    private function throwException(): void
55    {
56        throw new UnexpectedValueException('処理中に予期しない値が検出されました。');
57    }
58}
59
60// クラスのインスタンスを作成し、実行します。
61$example = new ExceptionTraceExample();
62$example->run();

このPHPサンプルコードは、プログラム実行中に例外が発生した際に、その原因を特定するために役立つgetTraceAsString()メソッドの使用例を示しています。コードでは、run()メソッドから複数のメソッドが順番に呼び出され、最終的にthrowException()メソッドで意図的にUnexpectedValueExceptionという種類の例外を発生させています。

try...catch構文によって、発生した例外はcatchブロックで例外オブジェクトとして捕捉されます。ここで中心となるのが、捕捉した例外オブジェクト$eに対して呼び出されるgetTraceAsString()メソッドです。このメソッドは引数を必要としません。戻り値として、例外が発生した地点から、そこに至るまでのメソッド呼び出しの履歴、すなわち「スタックトレース」を、人間が読みやすい形式の文字列として返します。この文字列には、どのファイルの何行目でどの関数が呼び出されたかといった詳細な情報が含まれています。

サンプルコードのようにこの文字列を出力することで、プログラムのどこで予期せぬ事態が発生したのかを正確に追跡でき、デバッグ作業を効率的に進めることが可能になります。

getTraceAsString()は、例外発生までの関数呼び出し履歴を文字列で取得するメソッドで、エラーの原因特定に役立ちます。注意点として、スタックトレースにはファイルパスなどの内部情報が含まれるため、本番環境の画面にそのまま表示するとセキュリティリスクになります。このため、利用は開発時のデバッグに限定し、本番環境ではエラーログに記録して、利用者には一般的なエラーメッセージを見せるようにしてください。プログラムでトレース情報を詳細に扱いたい場合は、配列を返すgetTrace()メソッドを利用します。