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

Copy
1<?php
2
3declare(strict_types=1);
4
5/**
6 * ユーザーデータを管理し、順位に基づいてユーザー情報を取得するクラス
7 */
8class UserRanking
9{
10    /**
11     * @var array<int, string> ユーザーリスト (キーは順位 - 1)
12     */
13    private array $users = [
14        'Alice', // 1位
15        'Bob',   // 2位
16        'Charlie', // 3位
17    ];
18
19    /**
20     * 指定された順位のユーザー名を取得します。
21     *
22     * @param int $rank 取得したいユーザーの順位 (1, 2, 3...)
23     * @return string ユーザー名
24     * @throws \OutOfRangeException 指定された順位が存在しない場合にスローされます。
25     */
26    public function findUserByRank(int $rank): string
27    {
28        // 順位が1未満、またはユーザー数より大きい場合は範囲外
29        if ($rank < 1 || $rank > count($this->users)) {
30            // OutOfRangeExceptionをスローする。
31            // 第1引数にエラーメッセージ、第2引数にエラーコードを指定する。
32            throw new \OutOfRangeException(
33                "指定された順位 ({$rank}) のユーザーは存在しません。",
34                1001 // 独自のエラーコード: 範囲外アクセス
35            );
36        }
37
38        // 配列のインデックスは0から始まるため、順位から1を引く
39        return $this->users[$rank - 1];
40    }
41}
42
43$ranking = new UserRanking();
44
45try {
46    // 範囲外の順位（例: 5位）を指定してユーザーを取得しようと試みる
47    $rank = 5;
48    echo "{$rank}位のユーザー: " . $ranking->findUserByRank($rank) . PHP_EOL;
49} catch (\OutOfRangeException $e) {
50    // 例外がスローされた場合に、このブロックが実行される
51    echo "エラーが発生しました。" . PHP_EOL;
52
53    // getCode() メソッドで、例外に設定されたエラーコードを取得する
54    $errorCode = $e->getCode();
55
56    // エラーメッセージとエラーコードを出力する
57    echo "メッセージ: " . $e->getMessage() . PHP_EOL;
58    echo "エラーコード: " . $errorCode . PHP_EOL;
59}

getCode()メソッドは、OutOfRangeExceptionのような例外オブジェクトから、それに設定された「エラーコード」を取得するために使用します。エラーコードは、なぜエラーが起きたのかをプログラムで識別しやすくするための数値や文字列です。

このメソッドは引数を必要としません。戻り値として、例外が作られた際に開発者が設定したエラーコードを整数(int)または文字列(string)で返します。もしエラーコードが設定されていなければ、通常は0が返されます。

サンプルコードでは、findUserByRankメソッド内で存在しない順位が指定された場合、OutOfRangeExceptionを発生させています。このとき、new OutOfRangeException()の第2引数に、独自のエラーコードとして1001が渡されています。

try...catchブロックでこの例外を捕捉した後、$e->getCode()を呼び出すことで、設定されていたエラーコード1001を取得しています。これにより、エラーメッセージの文字列に頼らずとも、エラーコードという決まった値でエラーの種類を正確に特定し、コードに応じた処理を記述することが可能になります。

Copy
1<?php
2
3/**
4 * 配列から指定されたインデックスの要素を取得します。
5 *
6 * @param array<int, mixed> $items データ配列
7 * @param int $index 取得したい要素のインデックス
8 * @return mixed 配列の要素
9 * @throws OutOfRangeException インデックスが配列の範囲外の場合にスローされます。
10 */
11function getItem(array $items, int $index): mixed
12{
13    if (!isset($items[$index])) {
14        // インデックスが配列の範囲外の場合、エラーメッセージと
15        // プログラムで識別可能な「エラーコード」(ここでは 1001) を設定して例外をスローします。
16        throw new OutOfRangeException('指定されたインデックスは範囲外です。', 1001);
17    }
18    return $items[$index];
19}
20
21$sampleArray = ['apple', 'banana', 'cherry'];
22$targetIndex = 5; // 存在しないインデックスを指定
23
24try {
25    // 例外が発生する可能性のあるコードを try ブロックで囲みます。
26    $item = getItem($sampleArray, $targetIndex);
27    echo "取得したアイテム: " . $item . PHP_EOL;
28} catch (OutOfRangeException $e) {
29    // OutOfRangeException がスローされた場合に、この catch ブロックで捕捉します。
30    echo "エラーが発生しました。" . PHP_EOL;
31    echo "メッセージ: " . $e->getMessage() . PHP_EOL;
32
33    // getCode() メソッドを使って、スローされた例外に設定されたエラーコードを取得します。
34    // このコードを利用して、エラーの種類に応じた処理を分岐させることができます。
35    $errorCode = $e->getCode();
36    echo "エラーコード: " . $errorCode . PHP_EOL;
37
38    if ($errorCode === 1001) {
39        echo "-> インデックスの指定に問題があるようです。" . PHP_EOL;
40    }
41}

OutOfRangeExceptionクラスのgetCode()メソッドは、発生した例外（エラー）に設定された「エラーコード」を取得するために使用します。エラーコードとは、人間が読むためのエラーメッセージとは別に、プログラムがエラーの種類を識別するために使われる数値や文字列のことです。

サンプルコードでは、配列の範囲外にあるインデックスを指定することで、意図的にOutOfRangeExceptionを発生させています。例外を発生させるthrow文の第二引数に、エラーコードとして 1001 という数値を設定しています。

try...catch構文のcatchブロックでこの例外を捕捉した後、$e->getCode()を呼び出すことで、先ほど設定したエラーコード 1001 を取得できます。このコードを利用すれば、if文などを使って「エラーコードが1001の場合、インデックス指定に問題がある」というように、エラーの種類に応じた具体的な処理を振り分けることが可能になります。

このメソッドに引数はなく、戻り値として、例外が作られた際に設定されたエラーコード（整数または文字列）が返されます。エラーコードが明示的に設定されていない場合は、デフォルトで整数の 0 が返されます。