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

Copy
1<?php
2
3/**
4 * 指定された値が正の整数であるか検証します。
5 *
6 * @param mixed $value 検証する値
7 * @return void
8 * @throws UnexpectedValueException 値が正の整数でない場合にスローされます
9 */
10function checkPositiveInteger(mixed $value): void
11{
12    // is_int()で整数か、かつ 0より大きいかをチェック
13    if (!is_int($value) || $value <= 0) {
14        // 期待しない値が渡された場合、エラーメッセージとエラーコード(1001)を指定して例外をスローします
15        throw new UnexpectedValueException('値は正の整数でなければなりません。', 1001);
16    }
17    echo "値 '{$value}' は有効です。" . PHP_EOL;
18}
19
20try {
21    // 正常に処理されるケース
22    checkPositiveInteger(100);
23
24    // 例外がスローされるケース (負の整数)
25    checkPositiveInteger(-5);
26
27} catch (UnexpectedValueException $e) {
28    // スローされた UnexpectedValueException をキャッチします
29    echo "--------------------------" . PHP_EOL;
30    echo "エラーをキャッチしました。" . PHP_EOL;
31    
32    // getMessage() で例外に設定されたメッセージを取得します
33    echo "メッセージ: " . $e->getMessage() . PHP_EOL;
34    
35    // getCode() で例外に設定されたエラーコード（整数）を取得します
36    // この場合、throw で指定した 1001 が出力されます
37    $errorCode = $e->getCode();
38    echo "エラーコード: " . $errorCode . PHP_EOL;
39}

PHPのUnexpectedValueException::getCode()メソッドは、スロー（発生）された例外オブジェクトに設定されている「エラーコード」を取得するためのものです。このメソッドは引数を必要とせず、戻り値として整数（int型）のエラーコードを返します。

サンプルコードでは、まずcheckPositiveIntegerという関数が定義されています。この関数は、引数として渡された値が正の整数でない場合に、エラーメッセージとエラーコード1001を持つUnexpectedValueExceptionをスローします。

tryブロック内でこの関数を呼び出し、checkPositiveInteger(-5)が実行されると、値が負の整数であるため例外が発生します。発生した例外はcatchブロックで捕捉されます。

catchブロック内では、捕捉した例外オブジェクト（変数$e）に対して$e->getCode()を実行しています。これにより、例外がスローされた際に第2引数として指定されたエラーコード1001が取得され、画面に表示されます。このようにgetCode()を利用することで、エラーメッセージに加えて、プログラムが識別しやすい数値コードでエラーの種類を特定し、コードに応じた分岐処理などを実装することが可能になります。

Copy
1<?php
2
3declare(strict_types=1);
4
5/**
6 * ユーザーデータを処理し、値が予期しない形式の場合に例外をスローします。
7 *
8 * この関数は、入力されたユーザーIDを検証します。
9 * IDが正の整数でない場合、エラーの種類に応じた例外コードを持つ
10 * UnexpectedValueExceptionをスローします。
11 *
12 * @param mixed $userId 検証するユーザーID
13 * @throws UnexpectedValueException ユーザーIDが不正な場合にスローされます。
14 *                                  - コード 1001: IDが整数ではない
15 *                                  - コード 1002: IDが正の数ではない
16 */
17function processUserData(mixed $userId): void
18{
19    // is_int()で値が整数型かチェック
20    if (!is_int($userId)) {
21        // 整数でない場合、例外コード1001で例外をスロー
22        throw new UnexpectedValueException('ユーザーIDは整数である必要があります。', 1001);
23    }
24
25    // 値が正の数かチェック
26    if ($userId <= 0) {
27        // 正の数でない場合、例外コード1002で例外をスロー
28        throw new UnexpectedValueException('ユーザーIDは正の整数である必要があります。', 1002);
29    }
30
31    echo "ユーザーID '{$userId}' の処理に成功しました。\n";
32}
33
34try {
35    // 正常なケース
36    processUserData(123);
37
38    // 例外が発生するケース (負の値)
39    processUserData(-5);
40
41} catch (UnexpectedValueException $e) {
42    // 例外(Exception)をキャッチする
43    echo "エラーが発生しました。\n";
44    
45    // getMessage() で例外メッセージを取得
46    echo "メッセージ: " . $e->getMessage() . "\n";
47    
48    // getCode() で例外コードを取得
49    $errorCode = $e->getCode();
50    echo "例外コード: " . $errorCode . "\n";
51
52    // 例外コードに基づいて、より具体的なエラーハンドリングを行う
53    switch ($errorCode) {
54        case 1001:
55            echo "対応: データ型が間違っています。システム管理者に連絡してください。\n";
56            break;
57        case 1002:
58            echo "対応: 値の範囲が不正です。入力内容を確認してください。\n";
59            break;
60        default:
61            echo "対応: 不明なエラーです。\n";
62            break;
63    }
64}
65
66?>

UnexpectedValueException::getCode()は、発生した例外に設定された「例外コード」を整数(int)で取得するためのメソッドです。例外処理において、エラーの具体的な原因をプログラムが識別する目的で使用されます。このメソッドは引数を必要としません。

返される例外コードは、throw new UnexpectedValueException('メッセージ', コード)のように、例外が生成される際にコンストラクタの第2引数として指定された数値です。もしコードが指定されずに例外がスローされた場合は、0が返されます。

サンプルコードのprocessUserData関数は、ユーザーIDの妥当性を検証します。IDが整数でない場合は例外コード1001を、正の数でない場合は1002を設定して、UnexpectedValueExceptionをスロー（発生）させます。

try...catchブロックでは、このスローされた例外を捕捉（キャッチ）します。catchブロック内では、例外オブジェクト$eに対して$e->getCode()を呼び出すことで、設定された1001や1002といったコードを取得しています。取得したコードをswitch文で判定することで、エラーの原因に応じた個別の対応処理を実装できます。このようにgetCode()は、画一的ではない、より詳細なエラーハンドリングを実現するために役立ちます。