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

Copy
1<?php
2
3/**
4 * 配列から指定されたインデックスの値を取得します。
5 * インデックスが範囲外の場合は RangeException をスローします。
6 *
7 * @param array<int, string> $data 検索対象の配列
8 * @param int $index 取得したい値のインデックス
9 * @return string 配列の要素
10 * @throws RangeException インデックスが配列の範囲外の場合
11 */
12function getValueFromArray(array $data, int $index): string
13{
14    if (!isset($data[$index])) {
15        // インデックスが範囲外の場合、RangeExceptionをスローする
16        throw new RangeException("インデックス {$index} は配列の範囲外です。");
17    }
18    return $data[$index];
19}
20
21// サンプルデータ配列
22$colors = [0 => 'Red', 1 => 'Green', 2 => 'Blue'];
23
24try {
25    // 範囲外のインデックス（例: 5）にアクセスしようと試みる
26    echo "インデックス 5 の値を取得しようとします..." . PHP_EOL;
27    $color = getValueFromArray($colors, 5);
28    echo $color . PHP_EOL;
29} catch (RangeException $e) {
30    // RangeExceptionをキャッチする
31    // 例外オブジェクト $e を echo すると、内部的に __toString() メソッドが呼び出される
32    // これにより、例外情報が整形された文字列として出力される
33    echo "例外がキャッチされました:" . PHP_EOL;
34    echo $e;
35}
36

このPHPサンプルコードは、配列の範囲外のインデックスにアクセスしようとした際に発生するRangeExceptionという例外を捕捉し、その内容を表示する例です。

getValueFromArray関数は、指定されたインデックスが配列の有効な範囲にない場合、new RangeException()で例外を意図的に発生させます。tryブロック内でこの関数をわざと範囲外のインデックス（5）で呼び出すことで、この例外が引き起こされます。

発生した例外はcatchブロックで捕捉されます。ここで重要なのが、RangeExceptionクラスに備わっている__toStringメソッドです。このメソッドは、オブジェクトが文字列として扱われる状況、例えばechoで出力される際に自動的に呼び出されます。このメソッドは引数を取らず、戻り値として例外に関する詳細情報（エラーメッセージ、発生したファイル名、行番号など）を人間が読みやすいように整形した文字列（string）を返します。

サンプルコードの echo $e; の部分では、捕捉した例外オブジェクト$eを直接出力しようとしています。これにより、内部で自動的に$e->__toString()メソッドが実行され、コンソールに例外の詳細が分かりやすく表示されます。このように__toStringメソッドは、例外オブジェクトの内容を簡単に確認する上で便利な機能です。

Copy
1<?php
2
3/**
4 * 指定された配列のインデックスから値を取得する関数。
5 *
6 * @param array<int, string> $data データ配列
7 * @param int $index 取得する値のインデックス
8 * @return string
9 * @throws RangeException インデックスが配列の範囲外の場合
10 */
11function getValueAtIndex(array $data, int $index): string
12{
13    // array_key_exists() でインデックスの存在を確認する
14    if (!array_key_exists($index, $data)) {
15        // インデックスが範囲外の場合、RangeExceptionをスローする
16        throw new RangeException("インデックス '{$index}' は有効な範囲外です。");
17    }
18    return $data[$index];
19}
20
21// サンプルデータ
22$users = [0 => 'Alice', 1 => 'Bob', 2 => 'Charlie'];
23
24try {
25    // 範囲外のインデックスを指定して、意図的に例外を発生させる
26    $user = getValueAtIndex($users, 5);
27    echo "ユーザー: " . $user . PHP_EOL;
28} catch (RangeException $e) {
29    // RangeExceptionを捕捉する
30    // 例外オブジェクト($e)を文字列として扱おうとすると、
31    // __toString() メソッドが自動的に呼び出される。
32    // これにより、例外クラス名、メッセージ、スタックトレースを含む
33    // 詳細なエラー情報が文字列として出力される。
34    echo "--- 例外情報 ---" . PHP_EOL;
35    echo $e;
36    echo PHP_EOL;
37    echo "----------------" . PHP_EOL;
38}

RangeExceptionクラスの__toString()メソッドは、例外オブジェクトを文字列として扱おうとした際に、その詳細情報を文字列形式で表現するために自動的に呼び出される特別なメソッドです。

このメソッドに引数はなく、戻り値として文字列（string）を返します。この文字列には、例外クラス名、コンストラクタで設定されたエラーメッセージ、例外が発生したファイル名と行番号、そしてそこに至るまでの処理の呼び出し履歴（スタックトレース）が含まれます。

サンプルコードでは、tryブロック内で配列の有効範囲外のインデックスを指定し、意図的にRangeExceptionを発生させています。続くcatchブロックでその例外オブジェクト$eを捕捉し、echoを使って直接出力しようとしています。この時、PHPはオブジェクトを文字列に変換するため、内部で自動的に$eの__toString()メソッドを呼び出します。結果として、例外に関する詳細なデバッグ情報が整形された文字列として画面に表示されます。