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

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

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

基本的な使い方

getTraceメソッドは、例外がスローされた時点のバックトレース（プログラムの実行経路）を取得するメソッドです。OutOfBoundsExceptionは、配列などで存在しないインデックスにアクセスしようとした場合に発生する例外です。このようなエラーが発生した際、プログラムのどの部分で問題が起きたのかを特定するために、どの関数やメソッドがどのような順序で呼び出されたかを知ることが不可欠です。このメソッドを呼び出すと、例外発生地点から遡って、関数やメソッドの呼び出し履歴が配列として返されます。返される配列の各要素は、呼び出しスタックの1フレームを表す連想配列となっており、ファイル名、行番号、関数名、クラス名、そしてその呼び出しで使われた引数などの詳細な情報を含んでいます。この詳細なトレース情報を利用することで、開発者はエラーの根本原因を効率的に突き止め、デバッグ作業を迅速に進めることができます。このメソッドは、基底クラスであるExceptionクラスで定義されているため、OutOfBoundsExceptionを含む全ての例外オブジェクトで利用可能です。

構文(syntax)


1<?php
2
3try {
4    $array = ['a', 'b'];
5    // 存在しないインデックスにアクセスすると OutOfBoundsException がスローされる
6    $value = $array[2];
7} catch (OutOfBoundsException $e) {
8    // 例外のスタックトレースを配列として取得する
9    $trace = $e->getTrace();
10    print_r($trace);
11}
12
13?>

引数(parameters)

引数なし

引数はありません

戻り値(return)

array

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

サンプルコード

PHP OutOfBoundsException getTraceAsStringで追跡する


1<?php
2
3/**
4 * 例外のスタックトレースを文字列として取得するデモ用の関数です。
5 */
6function demonstrateGetTraceAsString(): void
7{
8    // サンプルデータ
9    $items = ['apple', 'banana', 'cherry'];
10
11    try {
12        // 存在しない配列のインデックスにアクセスする関数を呼び出す
13        getItemByIndex($items, 5);
14    } catch (OutOfBoundsException $e) {
15        // 発生した例外をキャッチする
16        echo "例外がキャッチされました。\n";
17        echo "----------------------------------------\n";
18        
19        // Exception::getTraceAsString() メソッドを使用して、
20        // 例外が発生するまでの関数の呼び出し履歴（スタックトレース）を
21        // 文字列として取得し、出力します。
22        // これにより、どのファイルの何行目で、どの関数呼び出しが原因で
23        // 例外が発生したかを追跡できます。
24        echo $e->getTraceAsString();
25        
26        echo "----------------------------------------\n";
27    }
28}
29
30/**
31 * 配列とインデックスを受け取り、対応する要素を返します。
32 * インデックスが範囲外の場合は OutOfBoundsException をスローします。
33 *
34 * @param array $array 検索対象の配列
35 * @param int $index 取得する要素のインデックス
36 * @return mixed
37 * @throws OutOfBoundsException インデックスが配列の範囲外の場合
38 */
39function getItemByIndex(array $array, int $index): mixed
40{
41    if (!isset($array[$index])) {
42        // 配列の範囲外アクセスの場合、例外を意図的にスローする
43        throw new OutOfBoundsException("インデックス {$index} は範囲外です。");
44    }
45    return $array[$index];
46}
47
48// デモ関数を実行します
49demonstrateGetTraceAsString();

このPHPサンプルコードは、例外が発生した際のプログラムの実行経路を調べる Exception::getTraceAsString() メソッドの使い方を解説するものです。このメソッドは、OutOfBoundsException をはじめとする、Exception クラスを継承した全ての例外オブジェクトで使用できます。

コードでは、まず demonstrateGetTraceAsString 関数内で、わざと配列の範囲外となるインデックスを指定して getItemByIndex 関数を呼び出します。getItemByIndex 関数は、指定されたインデックスが配列の範囲外であるため、OutOfBoundsException という例外を意図的に発生させます。

try...catch 構文は、この発生した例外を catch ブロックで捕捉します。そして、捕捉した例外オブジェクト $e に対して getTraceAsString() メソッドを呼び出しています。このメソッドは引数を取らず、例外が発生するまでの一連の関数呼び出し履歴（スタックトレース）を、人間が読みやすい文字列形式で返します。出力された文字列には、どのファイルの何行目でどの関数が呼び出されたかといった情報が含まれるため、エラーの原因を特定するデバッグ作業で非常に役立ちます。

getTraceAsString()メソッドは、例外が発生するまでの処理の流れを文字列として取得できるため、プログラムのデバッグ時に原因を特定するのに非常に役立ちます。注意点として、このメソッドが返すスタックトレースには、ファイルパスや関数名といったシステムの内部情報が含まれます。そのため、開発中は便利ですが、本番環境でこの情報をそのまま画面に出力すると、セキュリティ上のリスクになり得ます。運用時には、エラー内容をユーザーに表示せず、ログファイルに記録するようにしましょう。