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

Copy
1<?php
2
3/**
4 * 指定されたインデックスで配列から色を検索し、見つからない場合は例外をスローします。
5 *
6 * @param array<int, string> $colors 色の配列
7 * @param int $index 検索するインデックス
8 * @return string 見つかった色
9 * @throws OutOfRangeException インデックスが配列の範囲外の場合
10 */
11function findColorByIndex(array $colors, int $index): string
12{
13    // 配列のキーが存在するかどうかを確認
14    if (!isset($colors[$index])) {
15        // インデックスが範囲外の場合、OutOfRangeExceptionをスローする
16        throw new OutOfRangeException("エラー: インデックス '{$index}' は配列の範囲外です。");
17    }
18    return $colors[$index];
19}
20
21// 検索対象の配列
22$colors = [0 => 'Red', 1 => 'Green', 2 => 'Blue'];
23
24try {
25    // 存在しないインデックス（範囲外）を指定して関数を呼び出す
26    $color = findColorByIndex($colors, 5);
27    echo "選択された色: " . $color . PHP_EOL;
28} catch (OutOfRangeException $e) {
29    // catchブロックで例外オブジェクトを捕捉する
30    // 例外オブジェクトをechoすると、自動的に__toString()メソッドが呼び出され、
31    // 例外情報が整形された文字列として出力される
32    echo $e;
33    echo PHP_EOL;
34}
35
36?>

このサンプルコードは、配列の範囲外のインデックスにアクセスした際に発生するOutOfRangeExceptionという例外を、__toStringメソッドを利用して文字列として出力する方法を示しています。

findColorByIndex関数は、引数で受け取ったインデックスが配列に存在しない場合、OutOfRangeExceptionをスロー（発生）させます。

try-catch構文は、例外が発生する可能性のある処理を安全に実行するための仕組みです。tryブロック内で、意図的に範囲外のインデックス5を指定して関数を呼び出すことで、例外を発生させています。発生した例外はcatchブロックで捕捉され、その例外オブジェクトが変数$eに代入されます。

echo $e;の行が__toStringメソッドの動作を示す中心部分です。OutOfRangeExceptionオブジェクトである$eをechoで直接出力しようとすると、PHPは自動的に__toStringメソッドを呼び出します。このメソッドは引数を取らず、戻り値としてオブジェクトの情報を表現する文字列（string）を返します。OutOfRangeExceptionの場合、エラーメッセージ、発生したファイル名、行番号など、デバッグに役立つ情報が整形された文字列として返され、画面に出力されます。

Copy
1<?php
2
3/**
4 * この関数は、配列から指定されたインデックスの値を取得します。
5 * インデックスが配列の範囲外の場合、OutOfRangeException をスローします。
6 *
7 * @param array<int, string> $array データを含む配列
8 * @param int $index アクセスするインデックス
9 * @return string 指定されたインデックスの値
10 * @throws OutOfRangeException インデックスが範囲外の場合
11 */
12function getValueByIndex(array $array, int $index): string
13{
14    if (!isset($array[$index])) {
15        // 配列の範囲外のインデックスが指定された場合、例外をスローする
16        throw new OutOfRangeException("指定されたインデックス {$index} は無効です。");
17    }
18    return $array[$index];
19}
20
21// メインの処理
22try {
23    // サンプルデータ
24    $fruits = [0 => 'apple', 1 => 'banana', 2 => 'cherry'];
25
26    // 存在しないインデックス（例: 5）にアクセスし、意図的に例外を発生させる
27    getValueByIndex($fruits, 5);
28
29} catch (OutOfRangeException $e) {
30    // OutOfRangeException をキャッチする
31    // 例外オブジェクト $e を echo で出力しようとすると、
32    // 内部的に __toString() メソッドが自動的に呼び出される。
33    // これにより、例外情報が整形された文字列として出力される。
34    echo "例外が発生しました:\n";
35    echo $e;
36}
37
38?>

OutOfRangeException::__toString()メソッドは、OutOfRangeExceptionオブジェクトが文字列として扱われる際に、そのオブジェクトを説明する文字列を自動的に生成して返すための特殊なメソッドです。このメソッドは引数を受け取らず、戻り値として例外情報（エラーメッセージ、発生箇所など）を含むstring（文字列）を返します。

提示されたサンプルコードは、配列の範囲外のインデックスにアクセスすることで意図的にOutOfRangeExceptionを発生させる例です。tryブロック内で例外が発生すると、catchブロックでその例外オブジェクトが変数$eに格納されます。

ここで重要なのはecho $e;という処理です。echoは通常、文字列を出力するための構文ですが、このようにオブジェクトが渡されると、PHPは内部で自動的にそのオブジェクトの__toString()メソッドを呼び出します。その結果、__toString()メソッドが返した、例外の詳細情報が整形された文字列が画面に出力されます。この仕組みにより、開発者は例外オブジェクトを直接echoするだけで、デバッグに必要な情報を簡単に確認することができます。