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

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

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

基本的な使い方

『getTraceメソッドは、例外が発生するまでのプログラムの実行経路、すなわちスタックトレースを取得するメソッドです』このメソッドはBadFunctionCallExceptionの親クラスであるExceptionクラスで定義されており、例外処理においてデバッグを行う際に極めて重要な役割を果たします。メソッドを呼び出すと、例外がスローされた地点に至るまでの関数呼び出しの履歴が配列形式で返されます。この配列の各要素は、呼び出しの一段階（スタックフレーム）を表しており、どのファイルの何行目で、どの関数が、どのような引数で呼び出されたかといった詳細な情報を含んでいます。例えば、存在しない関数を呼び出したり、関数の引数の数が間違っていたりしてBadFunctionCallExceptionが発生した場合に、このメソッドを使うことで、問題のコード箇所とそこに至るまでの呼び出しの流れを正確に特定できます。これにより、開発者はエラーの原因を迅速に突き止め、修正することが可能になります。

構文(syntax)


1<?php
2try {
3    // BadFunctionCallExceptionを発生させる例
4    call_user_func('存在しない関数');
5} catch (BadFunctionCallException $e) {
6    // 例外のスタックトレースを配列として取得する
7    $trace = $e->getTrace();
8    
9    print_r($trace);
10}
11?>

引数(parameters)

引数なし

引数はありません

戻り値(return)

array

発生した例外のトレース情報を格納した配列が返されます。

サンプルコード

PHP BadFunctionCallExceptionのgetTraceAsString()でトレースを取得する


1<?php
2
3/**
4 * このスクリプトは、BadFunctionCallExceptionを意図的に発生させ、
5 * その例外オブジェクトからgetTraceAsString()メソッドを使用して
6 * スタックトレースを文字列として取得し、表示するサンプルです。
7 */
8final class ExceptionTraceExample
9{
10    /**
11     * 2つの引数を必要とするメソッド
12     *
13     * @param int $a
14     * @param int $b
15     * @return int
16     */
17    private function add(int $a, int $b): int
18    {
19        return $a + $b;
20    }
21
22    /**
23     * BadFunctionCallExceptionを発生させ、スタックトレースを取得する
24     */
25    public function run(): void
26    {
27        try {
28            // BadFunctionCallExceptionを意図的に発生させます。
29            // 'add'メソッドは引数を2つ必要としますが、1つしか渡していません。
30            // このような不正な関数呼び出しにより、例外がスローされます。
31            call_user_func_array([$this, 'add'], [1]);
32        } catch (BadFunctionCallException $e) {
33            // 発生した例外を捕捉します。
34
35            // getTraceAsString()メソッドを使い、スタックトレースを文字列として取得します。
36            // スタックトレースは、エラーが発生するまでの関数の呼び出し履歴であり、
37            // デバッグに非常に役立ちます。
38            $traceString = $e->getTraceAsString();
39
40            // 取得したスタックトレースを出力します。
41            echo "例外が発生しました。\n";
42            echo "----------------------------------------\n";
43            echo "スタックトレース:\n";
44            echo $traceString;
45            echo "\n----------------------------------------\n";
46        }
47    }
48}
49
50// クラスのインスタンスを生成して実行します。
51$example = new ExceptionTraceExample();
52$example->run();

このPHPサンプルコードは、意図的に不正な関数呼び出しを行い、BadFunctionCallExceptionという例外を発生させます。そして、その例外オブジェクトが持つgetTraceAsString()メソッドを使い、エラー発生までの処理の呼び出し履歴（スタックトレース）を取得して表示する一連の流れを示しています。

コード内のrunメソッドでは、tryブロックでcall_user_func_array関数を用いています。ここで、2つの引数を必要とするaddメソッドを、引数を1つしか渡さずに呼び出そうとしています。このような引数の数が一致しない不正な呼び出しが原因で、BadFunctionCallExceptionが発生します。

catchブロックでは、発生した例外を$eという変数で捕捉します。ここで重要なのが$e->getTraceAsString()です。このメソッドは引数を取らず、例外が発生するまでの関数の呼び出し経路を、人間が読みやすい形式に整形された文字列として返します。この文字列には、どのファイルの何行目でどの関数が呼び出されたかといった詳細な情報が含まれており、プログラムの問題箇所を特定するデバッグ作業で非常に役立ちます。最後に、取得したスタックトレースの文字列を画面に出力して処理を終えます。

getTraceAsString()は、エラー発生までの処理の流れを文字列として取得でき、デバッグ時に原因を特定するのに非常に便利です。しかし、この文字列にはファイルパスなどの機密情報が含まれることがあるため、本番環境でユーザーにそのまま表示すると、セキュリティ上の脆弱性につながる危険があります。エラー情報は画面には表示せず、ログファイルに記録するようにしてください。また、このメソッドが返す文字列のフォーマットはPHPのバージョンによって変わる可能性があるため、プログラムで内容を解析する用途には不向きです。プログラムでトレース情報を個別に扱いたい場合は、配列で情報を返すgetTrace()メソッドの利用を検討しましょう。