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

Copy
1<?php
2
3/**
4 * データベース接続に失敗したことを示すカスタム例外。
5 * これが「原因」となる最初の例外になります。
6 */
7class DatabaseConnectionException extends Exception
8{
9}
10
11/**
12 * ユーザーデータを取得する関数。
13 * 内部でデータベース接続を試み、失敗した場合はそれを原因として
14 * UnderflowExceptionをスローします。
15 *
16 * @throws UnderflowException ユーザーデータが空の場合
17 */
18function fetchUserData(bool $connectionOk): array
19{
20    try {
21        // データベース接続を試みる（この例では失敗をシミュレート）
22        if (!$connectionOk) {
23            throw new DatabaseConnectionException('データベースに接続できませんでした。');
24        }
25        // 本来はここでデータを取得するが、この例では常に空とする
26        return [];
27    } catch (DatabaseConnectionException $e) {
28        // 捕捉した例外($e)を「前の例外」として設定し、
29        // 新しいUnderflowExceptionをスローします。
30        // これにより、エラーの連鎖（Exception Chaining）が作られます。
31        throw new UnderflowException(
32            'ユーザーデータの取得に失敗しました。結果が空です。',
33            0,
34            $e // ここで原因となった例外を渡す
35        );
36    }
37}
38
39// メインの処理
40try {
41    // データベース接続が失敗する状況で関数を呼び出します。
42    fetchUserData(false);
43} catch (UnderflowException $e) {
44    // 最終的にキャッチしたUnderflowExceptionの情報を出力します。
45    echo '現在の例外: ' . $e->getMessage() . PHP_EOL;
46    echo 'ファイル: ' . $e->getFile() . ' 行: ' . $e->getLine() . PHP_EOL;
47    echo '---' . PHP_EOL;
48
49    // getPrevious()メソッドを使って、この例外の直接の原因となった「前の例外」を取得します。
50    $previous = $e->getPrevious();
51
52    // 前の例外が存在するか確認します。
53    if ($previous instanceof Throwable) {
54        echo '原因となった例外: ' . $previous->getMessage() . PHP_EOL;
55        echo '原因の例外クラス: ' . get_class($previous) . PHP_EOL;
56        echo '原因のファイル: ' . $previous->getFile() . ' 行: ' . $previous->getLine() . PHP_EOL;
57    } else {
58        echo '原因となった例外はありません。' . PHP_EOL;
59    }
60}

UnderflowExceptionクラスのgetPrevious()メソッドは、ある例外が引き起こされる直接的な原因となった、一つ前の例外（previous exception）を取得するために使用します。このように例外を関連付けることを「例外の連鎖（Exception Chaining）」と呼び、エラーの根本原因を追跡する際に役立ちます。

このサンプルコードでは、まずfetchUserData関数内でデータベース接続の失敗を表すDatabaseConnectionExceptionが発生します。catchブロックではこの例外を捕捉し、それを原因として新たなUnderflowExceptionをスローしています。このとき、UnderflowExceptionのコンストラクタの第3引数に原因となった例外を渡すことで、2つの例外が関連付けられます。

メイン処理のcatchブロックでUnderflowExceptionを捕捉した後、$e->getPrevious()を呼び出すことで、その原因であるDatabaseConnectionExceptionのオブジェクトを取得できます。このメソッドは引数を取りません。戻り値は、原因となった例外オブジェクト、または原因が存在しない場合はnullとなります。そのため、if文で戻り値の存在を確認してから詳細情報を出力するのが安全です。これにより、表面的なエラーだけでなく、その背景にある根本的な問題までたどることが可能になります。