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

Copy
1<?php
2
3declare(strict_types=1);
4
5/**
6 * ユーザーの役割を検証するクラス
7 */
8class UserRoleValidator
9{
10    /** @var string[] 有効な役割のリスト */
11    private const ALLOWED_ROLES = ['admin', 'editor', 'viewer'];
12
13    /**
14     * 役割が有効かどうかを検証し、無効な場合は例外をスローします。
15     *
16     * @param string $role 検証する役割
17     * @return void
18     * @throws DomainException 役割が許可されたリストにない場合
19     */
20    public function validate(string $role): void
21    {
22        // 役割が許可された値のドメイン（範囲）に含まれているかチェック
23        if (!in_array($role, self::ALLOWED_ROLES, true)) {
24            // ドメイン外の値が指定されたため、DomainExceptionをスローする
25            // このとき、コンストラクタにエラーメッセージを渡す
26            throw new DomainException("無効な役割です: '{$role}'");
27        }
28        echo "役割 '{$role}' は有効です。\n";
29    }
30}
31
32$validator = new UserRoleValidator();
33
34try {
35    // 正常な値を渡すケース
36    $validator->validate('admin');
37
38    // DomainExceptionがスローされる値を渡すケース
39    $validator->validate('guest');
40
41} catch (DomainException $e) {
42    // スローされた例外を catch ブロックで捕捉する
43    // getMessage() メソッドを使い、例外オブジェクトに設定されたエラーメッセージを取得して表示する
44    echo "エラーが発生しました: " . $e->getMessage() . "\n";
45}

DomainExceptionクラスのgetMessage()メソッドは、発生した例外（エラー）オブジェクトに格納されているエラーメッセージを文字列として取得するために使用します。このメソッドに引数はありません。

サンプルコードでは、ユーザーの役割を検証するUserRoleValidatorクラスを定義しています。このクラスのvalidateメソッドは、引数で受け取った役割が、あらかじめ決められたリスト（'admin', 'editor', 'viewer'）に含まれているかを確認します。もしリストに含まれない値（例: 'guest'）が渡された場合、プログラムが期待する値の範囲（ドメイン）外であるとしてDomainExceptionという種類の例外をスロー（発生）させます。例外をスローする際、new DomainException("無効な役割です: '{$role}'") のように、コンストラクタへ具体的なエラー内容を示すメッセージを渡しています。

try...catch構文は、このような例外が発生する可能性のある処理を安全に実行するための仕組みです。tryブロック内でvalidate('guest')が実行されるとDomainExceptionがスローされ、プログラムは直ちにcatchブロックの処理に移ります。catchブロックでは、スローされた例外オブジェクトを$eという変数で捕捉（受け取り）します。そして、$e->getMessage()を呼び出すことで、例外発生時に設定されたエラーメッセージ「無効な役割です: 'guest'」を文字列として取得し、画面に出力しています。このようにgetMessage()は、エラーの原因を具体的に知るために重要な役割を果たします。

Copy
1<?php
2
3declare(strict_types=1);
4
5/**
6 * DomainException を継承したカスタム例外クラス。
7 * getMessage() メソッドをオーバーライドして、エラーメッセージの形式をカスタマイズします。
8 */
9class InvalidUsernameException extends DomainException
10{
11    /**
12     * PHP 8 のコンストラクタプロパティプロモーションを使用。
13     *
14     * @param string $invalidUsername 不正だったユーザー名
15     * @param string $message         エラーメッセージ
16     * @param int    $code            エラーコード
17     * @param ?Throwable $previous    前の例外
18     */
19    public function __construct(
20        private string $invalidUsername,
21        string $message = "",
22        int $code = 0,
23        ?Throwable $previous = null
24    ) {
25        // 必ず親クラスのコンストラクタを呼び出す
26        parent::__construct($message, $code, $previous);
27    }
28
29    /**
30     * 例外メッセージを返すメソッドをオーバーライド（再定義）します。
31     *
32     * 元のメッセージに加えて、どのユーザー名が不正だったかというコンテキスト情報を追加します。
33     *
34     * @return string フォーマットされたカスタムエラーメッセージ
35     */
36    public function getMessage(): string
37    {
38        // 親クラスが持つ元のメッセージを取得
39        $originalMessage = parent::getMessage();
40
41        // 不正な値と元のメッセージを組み合わせて、新しいメッセージを生成して返す
42        return sprintf(
43            "ユーザー名 '%s' の検証に失敗しました。理由: %s",
44            $this->invalidUsername,
45            $originalMessage
46        );
47    }
48}
49
50try {
51    $username = "admin!"; // 検証に失敗するユーザー名
52
53    // ユーザー名が英数字のみで構成されているか検証
54    if (!preg_match('/^[a-zA-Z0-9]+$/', $username)) {
55        // 検証に失敗した場合、カスタム例外をスロー(throw)する
56        throw new InvalidUsernameException($username, "許可されていない文字が含まれています。");
57    }
58
59    echo "ユーザー名 '{$username}' は有効です。" . PHP_EOL;
60
61} catch (InvalidUsernameException $e) {
62    // スローされた例外をキャッチ(catch)し、オーバーライドされた getMessage() の結果を出力する
63    echo "エラーが発生しました: " . $e->getMessage() . PHP_EOL;
64}
65
66?>

このPHPサンプルコードは、例外処理において親クラスのメソッドを再定義する「オーバーライド」というテクニックを使って、エラーメッセージをカスタマイズする方法を示しています。ここでは、PHPに組み込まれている DomainException を継承して、InvalidUsernameException という独自の例外クラスを作成しています。

このコードの重要な点は、getMessage() メソッドをオーバーライドしている部分です。getMessage() は、例外オブジェクトが持つエラーメッセージを取得するためのメソッドで、引数はなく、戻り値としてエラー内容の文字列 (string) を返します。

サンプル内の InvalidUsernameException クラスでは、この getMessage() の動作を変更しています。具体的には、parent::getMessage() を使って親クラスが元々持っているエラーメッセージを取得し、それに加えて「どのユーザー名が原因でエラーになったか」という独自の情報を付け加えて、より詳細なエラーメッセージを生成し直しています。

try-catch構文の中で、ユーザー名の検証に失敗した際にこのカスタム例外を発生させると、catchブロックで $e->getMessage() を呼び出したときに、このカスタマイズされた分かりやすいメッセージが出力されます。これにより、エラーの原因を特定しやすくなり、デバッグの効率が向上します。