【PHP8.x】UnexpectedValueException::codeプロパティの使い方

Copy
1<?php
2
3declare(strict_types=1);
4
5/**
6 * CodeIgniterのコンフィグサービスを模倣したサンプルのクラスです。
7 * 設定値が予期しないものであった場合に UnexpectedValueException を使用します。
8 */
9class ConfigValidator
10{
11    // アプリケーション固有のエラーコードを定数として定義しておくと便利です。
12    private const ERROR_CODE_EMPTY_KEY = 1001;
13    private const ERROR_CODE_INVALID_FORMAT = 1002;
14
15    /**
16     * APIキーの形式を検証します。
17     *
18     * CodeIgniterでは、このようなバリデーションはモデルやライブラリで行われます。
19     * 値が予期しない形式だった場合に、内容に応じたエラーコードを付けて例外をスローします。
20     *
21     * @param string $apiKey 検証対象のAPIキー
22     * @return bool 検証に成功した場合は true
23     * @throws UnexpectedValueException APIキーが空または不正な形式の場合
24     */
25    public function validateApiKey(string $apiKey): bool
26    {
27        if (empty($apiKey)) {
28            // 例外をスローする際、第2引数にエラーコード(int)を指定できます。
29            throw new UnexpectedValueException(
30                'APIキーが設定されていません。',
31                self::ERROR_CODE_EMPTY_KEY
32            );
33        }
34
35        if (!str_starts_with($apiKey, 'key_')) {
36            // 異なる問題には、異なるエラーコードを指定します。
37            throw new UnexpectedValueException(
38                'APIキーの形式が不正です。「key_」で始まる必要があります。',
39                self::ERROR_CODE_INVALID_FORMAT
40            );
41        }
42
43        return true;
44    }
45}
46
47// --- 以下、このクラスを利用する側のコード（例: CodeIgniterのコントローラ内の処理） ---
48
49$validator = new ConfigValidator();
50
51// 検証するAPIキーのサンプル
52$testApiKey = 'invalid-apikey';
53
54echo "APIキー '{$testApiKey}' の検証を開始します..." . PHP_EOL;
55
56try {
57    // 検証メソッドを実行
58    $validator->validateApiKey($testApiKey);
59    echo "APIキーは正常です。" . PHP_EOL;
60} catch (UnexpectedValueException $e) {
61    // UnexpectedValueException が発生した場合の処理
62    echo "エラーが発生しました: " . $e->getMessage() . PHP_EOL;
63
64    // $e->getCode() メソッドで、例外に設定された整数コードを取得します。
65    // このプロパティ（実際にはException基底クラスのプロパティ）がリファレンス情報の 'code' にあたります。
66    $errorCode = $e->getCode();
67
68    echo "例外コード: " . $errorCode . PHP_EOL;
69
70    // 取得したエラーコードに基づいて、具体的な対処法を示すなどの分岐処理が可能です。
71    switch ($errorCode) {
72        case 1001: // ERROR_CODE_EMPTY_KEY
73            echo "対処法: .env ファイルでAPIキーを設定してください。" . PHP_EOL;
74            break;
75        case 1002: // ERROR_CODE_INVALID_FORMAT
76            echo "対処法: 正しい形式のAPIキーを設定してください。" . PHP_EOL;
77            break;
78        default:
79            echo "対処法: 不明な設定エラーです。管理者に問い合わせてください。" . PHP_EOL;
80            break;
81    }
82}

UnexpectedValueExceptionが持つcodeプロパティは、例外に固有の整数コードを格納するために使用されます。このプロパティは、なぜエラーが発生したのかをプログラムが機械的に識別するための番号として機能します。

このPHPサンプルコードは、CodeIgniterなどのフレームワークで設定値を検証する処理を模倣しています。validateApiKeyメソッドでは、APIキーが空の場合や形式が不正な場合にUnexpectedValueExceptionをスロー（発生）させています。その際、コンストラクタの第二引数に、エラーの種類を区別するための整数コード（1001や1002）を指定しており、この値がcodeプロパティに設定されます。

呼び出し側ではtry...catch構文を使い、発生した例外を捕捉します。捕捉した例外オブジェクト（$e）に対してgetCode()メソッドを実行することで、codeプロパティに設定された整数値を取得できます。このgetCode()メソッドは引数を取らず、戻り値としてint型のコード番号を返します。取得したコードをswitch文で判定することにより、「キーが空である」「形式が不正である」といった具体的な原因に応じて処理を分岐させ、それぞれに合った対処法を示すといった、より丁寧なエラーハンドリングが可能になります。

Copy
1<?php
2
3declare(strict_types=1);
4
5/**
6 * 設定値を検証するクラス
7 *
8 * このコードは PHP_CodeSniffer (PSR-12) の規約に準拠しており、
9 * 予期しない値が与えられた場合に UnexpectedValueException を使用する例を示します。
10 */
11class ConfigValidator
12{
13    /**
14     * @var array<string> 許可された環境設定リスト
15     */
16    private const ALLOWED_ENVIRONMENTS = ['development', 'staging', 'production'];
17
18    /**
19     * @var int 無効な環境設定を示すエラーコード
20     */
21    public const E_INVALID_ENVIRONMENT = 4001;
22
23    /**
24     * 与えられた環境設定の値が有効かどうかを検証します。
25     *
26     * @param string $env 検証する環境設定の値
27     * @return void
28     * @throws UnexpectedValueException 値が許可リストにない場合にスローされます。
29     */
30    public function validateEnvironment(string $env): void
31    {
32        if (!in_array($env, self::ALLOWED_ENVIRONMENTS, true)) {
33            // 予期しない値が渡された場合、エラーメッセージとエラーコードを指定して例外をスローします。
34            throw new UnexpectedValueException(
35                "無効な環境設定です: {$env}",
36                self::E_INVALID_ENVIRONMENT
37            );
38        }
39    }
40}
41
42// --- メイン処理 ---
43
44$validator = new ConfigValidator();
45$testValue = 'test'; // 許可されていない値をテスト
46
47try {
48    // 設定値を検証します。
49    echo "環境設定 '{$testValue}' を検証します..." . PHP_EOL;
50    $validator->validateEnvironment($testValue);
51    echo "検証成功: '{$testValue}' は有効な設定です。" . PHP_EOL;
52} catch (UnexpectedValueException $e) {
53    // 例外をキャッチし、メッセージとエラーコードを取得して表示します。
54    // $e->code は Exception クラスから継承されたプロパティで、整数値のコードを返します。
55    echo "検証失敗: 例外がキャッチされました。" . PHP_EOL;
56    echo "  メッセージ: " . $e->getMessage() . PHP_EOL;
57    echo "  エラーコード: " . $e->getCode() . PHP_EOL;
58}

このサンプルコードは、与えられた設定値が、あらかじめ決められたリストに含まれているかを検証するものです。予期しない値が渡された場合に UnexpectedValueException を用いてエラーを処理する方法を示しています。

ConfigValidatorクラスのvalidateEnvironmentメソッドは、引数で受け取った環境設定の値が許可リストに存在しない場合、UnexpectedValueExceptionをthrow（スロー）します。この例外が生成される際、第1引数にエラーメッセージ、第2引数に独自のエラーコード（この例では4001）を渡すことができます。

メイン処理ではtry-catchブロックを使い、スローされた例外を捕捉（キャッチ）します。キャッチした例外オブジェクト$eのgetCode()メソッドを呼び出すと、例外生成時に指定したエラーコードを取得できます。このgetCode()メソッドは、親クラスであるExceptionから継承されたcodeプロパティの値を返すもので、引数はなく、戻り値はint型の整数です。このようにエラーコードを利用することで、エラーの種類をプログラムで識別し、その後の処理を分岐させることが容易になります。