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

Copy
1<?php
2
3declare(strict_types=1);
4
5/**
6 * 配列からインデックスを指定して値を取得します。
7 * 内部で発生した例外を、より具体的な例外でラップしてスローし直します。
8 *
9 * @param array<int, mixed> $data データ配列
10 * @param int $index 取得したい値のインデックス
11 * @return mixed 配列の値
12 * @throws OutOfRangeException インデックスが配列の範囲外の場合にスローされます。
13 */
14function getValueByIndex(array $data, int $index): mixed
15{
16    try {
17        // まず、インデックスが有効かどうかをチェックします。
18        // ここでは、引数が不正であるという低レベルな例外をスローします。
19        if (!array_key_exists($index, $data)) {
20            throw new InvalidArgumentException("インデックス {$index} は配列に存在しません。");
21        }
22        return $data[$index];
23    } catch (InvalidArgumentException $e) {
24        // 上記の InvalidArgumentException をキャッチします。
25        // そして、よりアプリケーションの文脈に合った OutOfRangeException を新たにスローします。
26        // このとき、コンストラクタの第3引数に元の例外($e)を渡すことで、
27        // 例外を「チェーン（連鎖）」させることができます。
28        throw new OutOfRangeException(
29            "配列の範囲外のインデックスが指定されました。",
30            0,
31            $e // <- 元の例外をここに渡す
32        );
33    }
34}
35
36// --- メイン処理 ---
37try {
38    $myArray = [10, 20, 30];
39
40    // 意図的に範囲外のインデックスを指定して関数を呼び出します。
41    echo "5番目の要素: " . getValueByIndex($myArray, 5) . PHP_EOL;
42} catch (OutOfRangeException $e) {
43    // getValueByIndex関数からスローされた OutOfRangeException をキャッチします。
44    echo "エラーが発生しました: " . $e->getMessage() . PHP_EOL;
45    echo "----------------------------------------" . PHP_EOL;
46
47    // getPrevious() メソッドを使い、この例外を引き起こした直接の原因（前の例外）を取得します。
48    $previousException = $e->getPrevious();
49
50    // 前の例外が存在する場合（nullでない場合）、その詳細情報を表示します。
51    if ($previousException !== null) {
52        echo "根本原因の情報 (Previous Exception):" . PHP_EOL;
53        echo "  - 例外クラス: " . get_class($previousException) . PHP_EOL;
54        echo "  - メッセージ: " . $previousException->getMessage() . PHP_EOL;
55        echo "  - 発生ファイル: " . $previousException->getFile() . PHP_EOL;
56        echo "  - 発生行: " . $previousException->getLine() . PHP_EOL;
57    } else {
58        echo "根本原因の情報はありません。" . PHP_EOL;
59    }
60}

OutOfRangeExceptionクラスのgetPrevious()メソッドは、連鎖している例外のうち、一つ前の例外オブジェクトを取得するために使用します。この仕組みを「例外チェーン」と呼びます。

このサンプルコードでは、getValueByIndex関数が配列の範囲外アクセスを検知すると、まず「引数が不正」というInvalidArgumentExceptionを発生させます。しかし、この例外をそのまま返すのではなく一度キャッチし、より状況を具体的に示すOutOfRangeExceptionで包み込み（ラップし）、再度スローします。このとき、元のInvalidArgumentExceptionが新しい例外に紐づけられます。

メイン処理では、このOutOfRangeExceptionをキャッチしたあと、getPrevious()メソッドを呼び出しています。これにより、OutOfRangeExceptionがスローされる根本原因となった、内部のInvalidArgumentExceptionオブジェクトを取得できます。このように、エラーの表面的な情報だけでなく、その原因を深く掘り下げて調査する際に役立ちます。

このメソッドに引数はありません。戻り値は、前の例外オブジェクト（Throwable型）です。連鎖する例外が存在しない場合はnullを返すため、使用前にnullチェックを行うのが一般的です。