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

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

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

基本的な使い方

getTraceメソッドは、例外がスローされた時点でのバックトレースを取得するメソッドです。バックトレースはスタックトレースとも呼ばれ、例外が発生するまでにプログラムが経由してきた関数やメソッドの呼び出し履歴を記録したものです。このメソッドを使用することで、エラーが発生した正確な場所だけでなく、そこに至るまでの処理の足跡を詳細に追跡することが可能になります。戻り値は配列形式であり、その配列の各要素が呼び出し履歴の一つのステップに対応しています。各ステップの情報は連想配列として格納され、ファイル名、行番号、関数名、クラス名、そして呼び出し時に使用された引数といった、デバッグに不可欠な情報が含まれています。この詳細な情報をログファイルに出力したり、エラー画面に表示したりすることで、開発者は問題の原因を効率的に特定し、修正作業を迅速に進めることができます。RuntimeExceptionクラスはPHPの標準的なExceptionクラスを継承しているため、このメソッドを利用できます。

構文(syntax)


1<?php
2
3try {
4    // 意図的に実行時例外を発生させます。
5    throw new RuntimeException("実行時エラーのサンプルです。");
6} catch (RuntimeException $e) {
7    // catchした例外オブジェクトの getTrace() メソッドを呼び出します。
8    // このメソッドは、例外が発生するまでのコールスタックを配列で返します。
9    $trace = $e->getTrace();
10
11    // 返された配列の内容を表示します。
12    print_r($trace);
13}
14
15?>

引数(parameters)

引数なし

引数はありません

戻り値(return)

array

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

サンプルコード

RuntimeExceptionのトレースを取得する


1<?php
2
3/**
4 * 複数のメソッド呼び出しを経て、意図的に例外を発生させるクラス。
5 */
6class ExceptionTracer
7{
8    /**
9     * 処理を開始し、次のメソッドを呼び出す。
10     */
11    public function startProcess(): void
12    {
13        $this->executeTask('Sample Data');
14    }
15
16    /**
17     * 中間処理を行い、さらに次のメソッドを呼び出す。
18     *
19     * @param string $data
20     */
21    private function executeTask(string $data): void
22    {
23        $this->generateError();
24    }
25
26    /**
27     * 意図的にRuntimeExceptionをスロー（発生）させる。
28     */
29    private function generateError(): void
30    {
31        // 実行時エラーを想定した例外を発生させます。
32        throw new RuntimeException("タスクの実行中に問題が発生しました。");
33    }
34}
35
36// メインの実行ブロック
37try {
38    // クラスのインスタンスを作成し、メソッドを実行します。
39    $tracer = new ExceptionTracer();
40    $tracer->startProcess();
41} catch (RuntimeException $e) {
42    // tryブロック内で発生したRuntimeExceptionをここで捕捉（キャッチ）します。
43    echo "エラー: " . $e->getMessage() . PHP_EOL . PHP_EOL;
44
45    // getTraceAsString() は、例外が発生するまでの関数やメソッドの呼び出し履歴（スタックトレース）を
46    // 整形された文字列として返します。
47    // この情報は、どこで問題が起きたのかを特定するための重要な手がかりとなります。
48    echo "--- スタックトレース ---" . PHP_EOL;
49    echo $e->getTraceAsString();
50}

PHPの getTraceAsString() は、例外が発生した際に、そこに至るまでのプログラムの実行経路（呼び出し履歴）を、人間が読みやすい形式の文字列として取得するためのメソッドです。このメソッドは引数を取らず、戻り値として整形されたスタックトレース情報の文字列を返します。

このサンプルコードでは、ExceptionTracer クラスのメソッドが startProcess() から executeTask()、generateError() の順で呼び出され、最終的に意図された RuntimeException が発生します。プログラムは try...catch ブロックでこの例外を捕捉（キャッチ）します。

catch ブロック内で、捕捉した例外オブジェクト $e に対して getTraceAsString() を呼び出しています。これにより、例外が発生した generateError() メソッドが、どのファイルのどの行で、どのメソッドから呼び出されたかという一連の流れが記録された文字列（スタックトレース）を取得できます。このスタックトレース情報は、エラーの原因がプログラムのどこにあるのかを特定するための非常に重要な手がかりとなり、デバッグ作業に欠かせません。

getTraceAsString()メソッドは、例外が発生するまでの処理の流れを文字列で取得します。この情報は「スタックトレース」と呼ばれ、どのファイルの何行目で、どのメソッド呼び出しがエラーの原因となったかを特定できるため、デバッグに非常に役立ちます。注意点として、スタックトレースにはファイルパスなどの内部情報が含まれる可能性があるため、本番環境でユーザーにそのまま表示するのは避けるべきです。代わりにエラーログファイルに記録し、開発者のみが確認できるようにすることが推奨されます。なお、似たメソッドにgetTrace()がありますが、こちらはスタックトレースを配列で返すため、プログラムで情報をさらに処理したい場合に使用します。