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

Copy
1<?php
2
3declare(strict_types=1);
4
5/**
6 * 指定されたインデックスの要素を取得する関数。
7 * 
8 * この関数は、内部でさらに別の関数を呼び出すことで、
9 * 例外発生時のスタックトレース（関数の呼び出し履歴）が長くなるようにしています。
10 *
11 * @param array<int, string> $items 商品リスト
12 * @param int $index 取得したい商品のインデックス
13 * @return string 商品名
14 */
15function findItem(array $items, int $index): string
16{
17    return checkIndexAndGetItem($items, $index);
18}
19
20/**
21 * 配列のインデックスが有効かチェックし、要素を返す関数。
22 *
23 * @param array<int, string> $data データ配列
24 * @param int $index チェックするインデックス
25 * @return string データ
26 * @throws OutOfRangeException インデックスが配列の範囲外の場合
27 */
28function checkIndexAndGetItem(array $data, int $index): string
29{
30    // 配列に指定されたインデックスが存在しない場合
31    if (!isset($data[$index])) {
32        // OutOfRangeExceptionを意図的にスローする
33        throw new OutOfRangeException("インデックス {$index} は範囲外です。");
34    }
35    return $data[$index];
36}
37
38// 商品リストのサンプル
39$itemList = [0 => 'Apple', 1 => 'Banana', 2 => 'Cherry'];
40
41try {
42    // 存在しないインデックス(5)を指定して、例外を発生させる
43    echo "商品リストからインデックス 5 の商品を探します...\n";
44    $item = findItem($itemList, 5);
45    echo "見つかった商品: " . $item . "\n";
46} catch (OutOfRangeException $e) {
47    // スローされたOutOfRangeExceptionをキャッチする
48    echo "エラー: 範囲外のインデックスが指定されました。\n\n";
49
50    // getTraceAsString()メソッドを呼び出す
51    // 例外が発生した地点までの関数の呼び出し履歴（スタックトレース）を
52    // 文字列として取得し、コンソールに出力する。
53    // これにより、エラーの原因調査が容易になる。
54    echo "--- スタックトレース ---\n";
55    echo $e->getTraceAsString();
56    echo "\n----------------------\n";
57}

OutOfRangeExceptionクラスのgetTraceAsString()メソッドは、例外が発生した時点の関数の呼び出し履歴、いわゆる「スタックトレース」を文字列として取得するためのものです。このメソッドは引数を取らず、戻り値としてスタックトレースが整形された文字列を返します。

このサンプルコードでは、まずfindItem()関数が、配列に存在しないインデックス（5）を指定してcheckIndexAndGetItem()関数を呼び出します。これにより、checkIndexAndGetItem()関数内でOutOfRangeExceptionが意図的に発生させられます。

プログラムはtry...catchブロックでこの例外を捕捉します。catchブロック内では、捕捉した例外オブジェクト（変数 $e）のgetTraceAsString()メソッドが呼び出されます。その結果、例外が発生したファイル名や行番号、そしてfindItem()からcheckIndexAndGetItem()へと関数が呼び出された経緯が、一つの文字列としてコンソールに出力されます。

このように、getTraceAsString()はエラー発生箇所だけでなく、そこに至るまでのプログラムの足跡を詳細に示してくれるため、エラーの原因調査（デバッグ）を行う上で非常に有効な手段となります。