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

Copy
1<?php
2
3/**
4 * 指定されたインデックスの要素を取得する関数
5 *
6 * この関数は、配列とインデックスを受け取り、インデックスが有効な範囲内にあるかチェックします。
7 * 範囲外の場合、OutOfRangeException をスローします。
8 *
9 * @param array<int, string> $data データ配列
10 * @param int $index 取得したい要素のインデックス
11 * @return string 指定されたインデックスの要素
12 * @throws OutOfRangeException インデックスが範囲外の場合
13 */
14function getElement(array $data, int $index): string
15{
16    // 配列のインデックスが有効な範囲にあるか確認
17    if (!isset($data[$index])) {
18        // インデックスが範囲外の場合、OutOfRangeExceptionのインスタンスを生成してスローする
19        // ここで __construct($message, $code) が呼び出される
20        throw new OutOfRangeException(
21            "インデックス {$index} は配列の範囲外です。", // 第1引数: $message
22            101                                      // 第2引数: $code
23        );
24    }
25
26    return $data[$index];
27}
28
29// サンプルデータ
30$colors = [0 => 'Red', 1 => 'Green', 2 => 'Blue'];
31
32try {
33    // 正常なケース: 有効なインデックスを指定
34    echo 'インデックス 1 の要素: ' . getElement($colors, 1) . PHP_EOL;
35
36    // 例外が発生するケース: 無効なインデックスを指定
37    echo 'インデックス 5 の要素: ' . getElement($colors, 5) . PHP_EOL;
38} catch (OutOfRangeException $e) {
39    // スローされた例外オブジェクトをキャッチする
40    echo '----------------------------' . PHP_EOL;
41    echo '例外がキャッチされました！' . PHP_EOL;
42    // コンストラクタで設定したメッセージとコードを取得して表示
43    echo 'メッセージ: ' . $e->getMessage() . PHP_EOL;
44    echo 'エラーコード: ' . $e->getCode() . PHP_EOL;
45}

OutOfRangeException::__constructは、OutOfRangeExceptionクラスのインスタンスが生成されるときに呼び出される、コンストラクタと呼ばれる特別なメソッドです。この例外クラスは、主に配列のインデックスや文字列のオフセットなどが有効な範囲を超えた場合に、エラーが発生したことをプログラムに知らせるために使用されます。

このコンストラクタは3つの引数を取ることができます。第1引数$messageには、なぜ例外が発生したのかを説明するためのエラーメッセージを文字列で指定します。第2引数$codeには、エラーの種類を識別するための数値を設定します。第3引数$previousは、この例外が別の例外に起因する場合に、その元の例外を関連付けるために使います。

サンプルコードでは、関数getElement内で配列の範囲外のインデックスが指定された際、new OutOfRangeException()でインスタンスを生成しています。このとき、コンストラクタに具体的なエラーメッセージとエラーコード101を渡しています。catchブロックでは、この例外オブジェクトを受け取り、getMessage()とgetCode()メソッドを使って、コンストラクタで設定した情報を取得・表示しています。このように、エラー発生時の詳細な状況を後続の処理に伝えることができます。なお、コンストラクタ自体に特定の戻り値はありません。

Copy
1<?php
2
3/**
4 * 指定された配列のインデックスから値を取得します。
5 * インデックスが範囲外の場合、OutOfRangeExceptionをスローします。
6 *
7 * @param array $data 対象の配列
8 * @param int $index 取得したい要素のインデックス
9 * @return mixed 配列の要素
10 * @throws OutOfRangeException インデックスが配列の範囲外の場合にスローされます。
11 */
12function getValueAt(array $data, int $index): mixed
13{
14    // 配列のインデックスが存在するかどうかをチェックします。
15    if (!array_key_exists($index, $data)) {
16        // --- OutOfRangeExceptionのコンストラクタ呼び出し ---
17        // 範囲外アクセスが検出されたため、例外オブジェクトを生成してスローします。
18        // public OutOfRangeException::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
19
20        // 第1引数: string $message
21        // 人が読んで理解できるエラーメッセージを指定します。
22        $message = "指定されたインデックス '{$index}' は範囲外です。";
23
24        // 第2引数: int $code
25        // プログラムでエラーの種類を識別するためのユニークなコードを指定します。
26        $code = 1001;
27
28        // 第3引数: ?Throwable $previous
29        // この例外が発生する直接の原因となった、別の例外オブジェクトを指定します。
30        // 例外をチェーン(連鎖)させ、根本原因の追跡を容易にします。
31        // ここでは原因となる例外がないため null を指定します。
32        $previous = null;
33
34        throw new OutOfRangeException($message, $code, $previous);
35    }
36
37    return $data[$index];
38}
39
40// --- メイン処理 ---
41$scores = [10 => 85, 20 => 92, 30 => 78];
42$targetIndex = 99; // 存在しないインデックス
43
44try {
45    // 範囲外のインデックスで関数を呼び出し、例外を発生させます。
46    echo "インデックス {$targetIndex} のスコアを取得します...\n";
47    $score = getValueAt($scores, $targetIndex);
48    echo "スコア: {$score}\n";
49} catch (OutOfRangeException $e) {
50    // throwされたOutOfRangeExceptionオブジェクトをここで捕捉します。
51    echo "エラー: OutOfRangeExceptionがキャッチされました。\n";
52
53    // getMessage()でコンストラクタに渡したメッセージを取得できます。
54    echo "メッセージ: " . $e->getMessage() . "\n";
55
56    // getCode()でコンストラクタに渡したエラーコードを取得できます。
57    echo "エラーコード: " . $e->getCode() . "\n";
58
59    // getPrevious()で、原因となった例外(今回はnull)を取得できます。
60    if ($e->getPrevious() !== null) {
61        echo "原因となった例外: " . $e->getPrevious()->getMessage() . "\n";
62    }
63}

OutOfRangeExceptionのコンストラクタ__constructは、この例外クラスの新しいインスタンス（オブジェクト）を生成するために使用されます。この例外は、配列の範囲外のインデックスにアクセスしようとした場合など、無効なキーが要求されたことを示すためにスローされます。

コンストラクタは3つの引数を取ります。第1引数の$messageには、開発者が読んで理解できるエラー内容を示す文字列を指定します。第2引数の$codeには、プログラムがエラーの種類を識別するための整数コードを指定します。第3引数の$previousには、この例外がスローされる直接的な原因となった、先行する別の例外オブジェクトを指定できます。これにより例外を連鎖させ、エラーの根本原因の追跡を容易にします。原因となる例外がない場合はnullを渡します。コンストラクタはオブジェクトの生成が目的のため、特定の戻り値はありません。

サンプルコードでは、配列に存在しないインデックスが指定された際に、new OutOfRangeException()で例外オブジェクトを生成しthrowしています。catchブロックではこのオブジェクトを捕捉し、getMessage()やgetCode()といったメソッドを使って、コンストラクタで設定したエラーメッセージやコードを取得していることが確認できます。