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

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

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

基本的な使い方

『getTraceメソッドは、例外がスローされた時点のバックトレースを配列として取得するメソッドです。バックトレースとは、例外が発生するまでにプログラムがたどってきた関数やメソッドの呼び出し履歴のことを指します。このメソッドを利用することで、どのような処理の流れを経てエラー発生地点に至ったのかを正確に把握できるため、デバッグ作業において非常に重要な役割を果たします。返り値は多次元配列であり、配列の各要素が呼び出しスタックの一つの階層（フレーム）に対応します。各要素には、呼び出し元のファイルパスを示すfileキー、行番号を示すlineキー、呼び出された関数名やメソッド名を示すfunctionキー、そして渡された引数の配列を保持するargsキーなどが含まれています。UnderflowExceptionのような実行時エラーが発生した際にこのメソッドを使用することで、問題の操作がプログラムのどこから呼び出されたのかを特定し、原因究明を効率的に進めることが可能になります。このメソッドは基底クラスであるExceptionクラスから継承された機能です。

構文(syntax)


1<?php
2
3function cause_underflow()
4{
5    throw new UnderflowException("An underflow exception occurred.");
6}
7
8try {
9    cause_underflow();
10} catch (UnderflowException $e) {
11    $trace = $e->getTrace();
12    print_r($trace);
13}
14
15?>

引数(parameters)

引数なし

引数はありません

戻り値(return)

array

例外発生時のコールスタック（呼び出し履歴）の配列を返します。配列の各要素は、例外発生までの関数呼び出しやメソッド呼び出しの情報を格納しています。

サンプルコード

PHP: UnderflowExceptionのgetTraceAsStringを取得する


1<?php
2
3declare(strict_types=1);
4
5/**
6 * スタックトレースのデモンストレーションを行うためのクラス
7 */
8class StackTraceDemo
9{
10    /**
11     * 空のスタックから要素をポップしようとして例外を発生させるメソッド
12     *
13     * @throws UnderflowException 意図的にスローされる例外
14     */
15    private function popFromEmptyStack(): void
16    {
17        // SplStackは空の状態でpop()を呼ぶとUnderflowExceptionをスローする
18        $stack = new SplStack();
19        $stack->pop();
20    }
21
22    /**
23     * 中間的な処理を行うメソッド
24     */
25    private function process(): void
26    {
27        // 例外を発生させるメソッドを呼び出す
28        $this->popFromEmptyStack();
29    }
30
31    /**
32     * プログラムを実行し、例外を捕捉してスタックトレースを出力する
33     *
34     * @return void
35     */
36    public function run(): void
37    {
38        try {
39            // 例外が発生する可能性のあるコードを実行
40            $this->process();
41        } catch (UnderflowException $e) {
42            // UnderflowExceptionを捕捉する
43            echo "例外がキャッチされました。\n\n";
44            echo "--- スタックトレース (getTraceAsString) ---\n";
45            
46            // Exception::getTraceAsString() は、例外がスローされた時点での
47            // 関数の呼び出し履歴（バックトレース）を整形された文字列として返す。
48            // これにより、どのファイルの何行目で、どの関数が呼び出されたかを追跡できる。
49            echo $e->getTraceAsString();
50            
51            echo "\n--- 処理終了 ---\n";
52        }
53    }
54}
55
56// クラスのインスタンスを作成して実行
57$demo = new StackTraceDemo();
58$demo->run();
59

このPHPサンプルコードは、意図的に例外を発生させ、その発生源を追跡する方法を示しています。StackTraceDemoクラスは、最終的に空のスタックからデータを取り出そうとしてUnderflowExceptionという例外を発生させる処理を含んでいます。

runメソッドでは、例外が発生する可能性のある処理をtryブロックで囲んでいます。もしtryブロック内でUnderflowExceptionが発生すると、プログラムは中断されずにcatchブロックの処理へと移り、発生した例外を捕捉します。

catchブロック内で呼び出されているgetTraceAsString()メソッドは、例外オブジェクトが持つ機能の一つです。このメソッドは引数を必要とせず、例外が発生するまでの一連のメソッド呼び出し履歴（スタックトレース）を、人間が読みやすい形式の文字列として返します。出力される文字列には、どのファイルの何行目で、どのメソッドが呼び出されたかといった詳細な情報が含まれます。これにより、エラーがどこで、どのような経緯で発生したのかを正確に把握でき、デバッグ作業で非常に役立ちます。

getTraceAsString()メソッドは、エラーが発生した箇所に至るまでの関数の呼び出し履歴を文字列として取得でき、デバッグの際に原因を特定するのに非常に役立ちます。ただし、この文字列にはファイルパスなどのシステム内部情報が含まれる点に注意が必要です。開発中の確認には便利ですが、本番環境でこの情報をそのまま画面に出力すると、攻撃者に重要な情報を与えることになり、セキュリティ上のリスクとなります。本番環境では、スタックトレースはログファイルに記録し、ユーザーには一般的なエラーメッセージを表示するように実装するのが安全な方法です。