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

Copy
1<?php
2
3/**
4 * `match` 式が未処理の値に遭遇した場合に発生する UnhandledMatchError を捕捉し、
5 * そのエラーコードを表示するサンプルです。
6 *
7 * CodeIgniterなどのフレームワークで構築されたアプリケーションにおいて、
8 * ユーザー入力の処理やAPIエンドポイントのルーティングロジックなどで
9 * このようなエラーが発生する可能性があります。
10 * システムエンジニアの初心者向けに、エラーの捕捉と情報取得の基本を示します。
11 *
12 * @param string $statusIdentifier 処理識別子
13 * @return string 処理結果またはエラーメッセージ
14 */
15function processApplicationStatus(string $statusIdentifier): string
16{
17    try {
18        // `match` 式を使用し、特定のステータス識別子を処理します。
19        // ここでは 'success' と 'failure' のみが定義されており、
20        // それ以外の値は UnhandledMatchError を引き起こします。
21        // （例: CodeIgniterのコントローラで、リクエストパラメータに応じて処理を分岐する場面など）
22        $message = match ($statusIdentifier) {
23            'success' => '処理が正常に完了しました。',
24            'failure' => '処理が失敗しました。',
25            // `default` ケースがないため、'success' または 'failure' 以外の値は UnhandledMatchError を発生させます。
26        };
27        return $message;
28    } catch (UnhandledMatchError $e) {
29        // UnhandledMatchError を捕捉し、エラーメッセージとエラーコードを取得します。
30        // このエラーコード (getCode()) は、UnhandledMatchError の場合、PHPの内部実装により通常 0 を返します。
31        // エラーを捕捉し、その詳細情報（メッセージとコード）を利用できることが重要です。
32        // CodeIgniterアプリケーションでは、この情報をログに記録したり、
33        // クライアントに適切なHTTPステータスコードと共にエラーレスポンスを返したりすることが考えられます。
34        return "エラーが発生しました: " . $e->getMessage() . " (エラーコード: " . $e->getCode() . ")";
35    }
36}
37
38// --- サンプル実行 ---
39
40// 正常に処理されるケース
41echo "ケース1 (正常): " . processApplicationStatus('success') . PHP_EOL;
42
43// UnhandledMatchError が発生し、捕捉されるケース
44echo "ケース2 (エラー): " . processApplicationStatus('pending') . PHP_EOL;
45

このサンプルコードは、PHP 8で導入されたmatch式が未処理の値に遭遇した場合に発生するUnhandledMatchErrorを捕捉し、そのエラーコードを取得する方法を示しています。processApplicationStatus関数は、$statusIdentifierという文字列の引数を受け取り、match式を使って特定のステータスに応じてメッセージを生成します。しかし、'success'と'failure'以外の値が渡された場合、match式に該当するケースがないためUnhandledMatchErrorが発生します。

このエラーはtry-catchブロックによって捕捉されます。catch (UnhandledMatchError $e)でエラーオブジェクト$eを受け取り、そこから$e->getMessage()でエラーの詳細な説明を、$e->getCode()でエラーコードを取得しています。UnhandledMatchErrorにおけるcodeプロパティ（getCode()の戻り値）は、PHPの内部実装により通常0を返しますが、エラーが発生したことをプログラマが特定し、適切な処理を行うための重要な情報源となります。

システムエンジニアを目指す初心者の方にとって、このようにエラーを捕捉し、その詳細情報（メッセージやコード）を利用して問題解決や適切なユーザーフィードバックを行う基本は非常に重要です。CodeIgniterなどのフレームワークで構築されたアプリケーションでは、ユーザーからの不正な入力や予期せぬAPIリクエストに対して、このエラー捕捉の仕組みを利用してエラーログを記録したり、ユーザーに分かりやすいエラーメッセージを返すことで、システムの堅牢性を高めることができます。関数は最終的に、処理が成功した場合は結果メッセージを、エラーが発生した場合はエラー情報を含む文字列を返します。

Copy
1<?php
2
3/**
4 * PHP 8 で導入された UnhandledMatchError のエラーコード取得方法を示すサンプル。
5 *
6 * この関数は、match 式がすべての可能な値を網羅していない場合に発生する
7 * UnhandledMatchError を意図的に発生させ、そのエラーオブジェクトから
8 * エラーコード（通常は 0）を取得する方法を実演します。
9 *
10 * @param string $value match 式の評価に使用する値。
11 * @return int 捕捉された UnhandledMatchError のエラーコード、またはエラーが発生しなかった場合は 0。
12 *             リファレンスの「名前: code, 引数: なし, 戻り値: int」は、
13 *             実際には `Throwable` インターフェースが提供する `getCode()` メソッドを指します。
14 */
15function demonstrateUnhandledMatchErrorCode(string $value): int
16{
17    try {
18        // match 式を使用し、意図的に UnhandledMatchError を発生させるケースを作成。
19        // 'handled_case' 以外の値が渡された場合、対応するアームがないため
20        // UnhandledMatchError がスローされます。
21        $result = match ($value) {
22            'handled_case' => 'この値は処理されました。',
23            // 'default' や他のケースがないため、網羅されない値はエラーになります。
24        };
25        echo "マッチ結果: " . $result . PHP_EOL;
26        return 0; // エラーが発生しなかった場合のコード
27    } catch (UnhandledMatchError $e) {
28        // UnhandledMatchError を捕捉します。
29        echo "UnhandledMatchError を捕捉しました: " . $e->getMessage() . PHP_EOL;
30        // エラーオブジェクトからエラーコードを取得します。
31        // UnhandledMatchError のコードは通常 0 です。
32        return $e->getCode();
33    } catch (Throwable $e) {
34        // UnhandledMatchError 以外の予期しないエラーを捕捉します。
35        echo "予期せぬエラーを捕捉しました: " . $e->getMessage() . PHP_EOL;
36        return $e->getCode();
37    }
38}
39
40// --- サンプル実行 ---
41
42// 1. UnhandledMatchError を発生させるケース
43echo "--- シナリオ1: UnhandledMatchError の発生 ---" . PHP_EOL;
44$errorCode = demonstrateUnhandledMatchErrorCode('unhandled_case');
45echo "捕捉された UnhandledMatchError のエラーコード: " . $errorCode . PHP_EOL;
46echo PHP_EOL;
47
48// 2. UnhandledMatchError が発生しないケース
49echo "--- シナリオ2: UnhandledMatchError が発生しない場合 ---" . PHP_EOL;
50$errorCode = demonstrateUnhandledMatchErrorCode('handled_case');
51echo "UnhandledMatchError は発生しませんでした。返されたコード: " . $errorCode . PHP_EOL;
52

このPHPコードは、PHP 8で導入されたUnhandledMatchErrorというエラーの捕捉方法と、そのエラーコードの取得方法を示しています。UnhandledMatchErrorは、match式で処理対象となる値に対応するケースが一つも定義されていない場合に発生します。

demonstrateUnhandledMatchErrorCode関数は、$valueという文字列型の引数を取り、この値を用いてmatch式を評価します。関数は、UnhandledMatchErrorを捕捉した場合にそのエラーコード（通常は0）を整数型で返します。エラーが発生しなかった場合は0を返します。

この関数では、try-catchブロックを用いてmatch式がスローするUnhandledMatchErrorを捕捉しています。捕捉したエラーオブジェクトから$e->getCode()を呼び出すことでエラーコードを取得します。リファレンスにあるUnhandledMatchErrorのcodeは、実際には基底となるThrowableインターフェースが提供するgetCode()メソッドで取得されることを意味しています。このコードは、UnhandledMatchErrorが発生するシナリオと発生しないシナリオの両方を通じて、具体的なエラーハンドリングの挙動を分かりやすく説明しています。

Copy
1<?php
2
3/**
4 * PHP 8で導入されたUnhandledMatchErrorを意図的に発生させ、
5 * その`code`プロパティにアクセスするサンプルコードです。
6 *
7 * UnhandledMatchErrorは、`match`式が全ての可能な値を網羅していない（網羅性がない）場合にスローされます。
8 * `code`プロパティは、エラーオブジェクトが持つエラーコード（整数）を返します。
9 *
10 * このコードはPHPの推奨コーディングスタイル（PSR-12など）に従っており、
11 * PHP CodeSnifferなどのツールでチェックしても問題ないように書かれています。
12 */
13
14/**
15 * `match`式を使用して入力値を処理する関数。
16 * 特定の入力値に対して`match`ケースが存在しない場合、
17 * UnhandledMatchErrorをスローするように意図的に設計されています。
18 *
19 * @param string $input 処理する文字列
20 * @return string
21 */
22function processValueWithMatch(string $input): string
23{
24    // PHP 8の`match`式は厳密な比較（===）を行います。
25    // また、全ての可能な入力値に対してケースを網羅している必要があります。
26    // この例では、'baz'が入力された場合に一致するケースがないため、
27    // `UnhandledMatchError`が発生します。
28    return match ($input) {
29        'foo' => '入力は "foo" です。',
30        'bar' => '入力は "bar" です。',
31        // 'baz' のケースは意図的に定義されていません。
32        // もし'baz'が渡された場合、ここに到達し、UnhandledMatchErrorがスローされます。
33    };
34}
35
36// エラー発生状況とその捕捉を実演するためのtry-catchブロック
37try {
38    echo "--- 正常なケースの実行 ---\n";
39    // 正常に処理される呼び出し
40    echo processValueWithMatch('foo') . "\n";
41    echo processValueWithMatch('bar') . "\n";
42
43    echo "\n--- エラー発生ケースの実行 ---\n";
44    // ここで`UnhandledMatchError`が発生します。
45    // 'baz'は`match`式で定義されていないためです。
46    echo processValueWithMatch('baz') . "\n";
47} catch (UnhandledMatchError $e) {
48    // `UnhandledMatchError`を捕捉し、エラー情報を表示します。
49    echo "UnhandledMatchError を捕捉しました！\n";
50    echo "エラーメッセージ: " . $e->getMessage() . "\n";
51
52    // UnhandledMatchErrorクラスの`code`プロパティにアクセスし、エラーコードを取得します。
53    // デフォルトでは、このプロパティの値は `0` になります。
54    echo "エラーコード (codeプロパティ): " . $e->code . "\n";
55} catch (Throwable $e) {
56    // 他の種類の`Throwable`（エラーや例外）を捕捉する場合のフォールバックです。
57    echo "予期せぬエラーを捕捉しました！\n";
58    echo "エラーの種類: " . get_class($e) . "\n";
59    echo "エラーメッセージ: " . $e->getMessage() . "\n";
60    echo "エラーコード: " . $e->getCode() . "\n";
61}

このPHPサンプルコードは、PHP 8で導入されたUnhandledMatchErrorと、そのcodeプロパティの動作をシステムエンジニアを目指す初心者の方に分かりやすく説明します。UnhandledMatchErrorは、PHP 8のmatch式を使用する際、全ての可能な入力値に対して処理が定義されていない（網羅されていない）場合に発生する、特別なエラーです。match式は、厳密な比較を行い、必ず全てのケースを網羅する必要があります。

UnhandledMatchErrorクラスが持つcodeプロパティは、このエラーオブジェクトが表すエラーの種類を示す整数値（エラーコード）を返します。このプロパティにアクセスする際に引数は必要なく、常にint型の値を戻り値として提供します。

サンプルコードでは、processValueWithMatch関数内でmatch式を使い、'baz'という特定の入力値に対するケースを意図的に定義していません。このため、processValueWithMatch('baz')が呼び出されると、UnhandledMatchErrorがスローされます。

try-catchブロックを用いることで、発生したUnhandledMatchErrorを安全に捕捉し、そのエラー情報を取り出しています。$e->codeとしてcodeプロパティにアクセスすると、エラーコードを取得できます。UnhandledMatchErrorの場合、このcodeプロパティのデフォルト値は通常0となります。このプロパティは、エラーの発生状況を数値として識別する際に役立ちます。コード全体はPHPの推奨コーディングスタイルに準拠しています。

Copy
1<?php
2
3/**
4 * 特定のステータス値に対応するメッセージを返す関数。
5 * 意図的にすべての可能なステータスを網羅しないことで、
6 * UnhandledMatchErrorが発生する可能性を示します（PHP 8以降）。
7 *
8 * @param int $status 処理のステータスコード
9 * @return string ステータスに応じた説明メッセージ
10 * @throws UnhandledMatchError match式がすべてのケースを網羅していない場合にスローされます。
11 */
12function getStatusMessage(int $status): string
13{
14    // PHP 8で導入されたmatch式を使用。
15    // この例では、特定のステータス（例：3）に対するケースを意図的に省略しています。
16    // これにより、$statusが3の場合にUnhandledMatchErrorが発生します。
17    return match ($status) {
18        0 => "処理は正常に完了しました。",
19        1 => "一時的なエラーが発生しました。再試行してください。",
20        2 => "致命的なエラーが発生しました。システム管理者に連絡してください。",
21        // もし以下のdefault句を有効にすると、UnhandledMatchErrorは発生しなくなります。
22        // default => "不明なステータスです。"
23    };
24}
25
26/**
27 * UnhandledMatchErrorの発生と、そのエラーコードの取得方法をデモンストレーションします。
28 *
29 * これは、php code checkerの観点から、コードの網羅性不足によって発生するエラーの
30 * ハンドリングと、エラーコードの取得方法の一例を示します。
31 */
32function demonstrateUnhandledMatchErrorHandling(): void
33{
34    echo "--- UnhandledMatchError ハンドリングのデモンストレーション ---\n";
35
36    // 正常に処理されるケース
37    echo "テストケース: ステータス 0\n";
38    try {
39        $message = getStatusMessage(0);
40        echo "  結果: " . $message . "\n";
41    } catch (UnhandledMatchError $e) {
42        // このケースではエラーは発生しないため、ここには到達しません。
43        echo "  エラーを捕捉しました: " . $e->getMessage() . " (コード: " . $e->getCode() . ")\n";
44    }
45
46    echo "\n";
47
48    // UnhandledMatchErrorが発生するケース
49    echo "テストケース: ステータス 3 (UnhandledMatchError発生)\n";
50    try {
51        // getStatusMessage関数に、match式で定義されていない値 '3' を渡すことで、
52        // UnhandledMatchErrorがスローされます。
53        $message = getStatusMessage(3);
54        echo "  結果: " . $message . "\n"; // エラー発生のため、ここには到達しません。
55    } catch (UnhandledMatchError $e) {
56        // UnhandledMatchErrorを捕捉し、その詳細情報を表示します。
57        echo "  UnhandledMatchErrorを捕捉しました。\n";
58        echo "  メッセージ: " . $e->getMessage() . "\n";
59        // UnhandledMatchError::code プロパティから、エラーコード（int型）を取得します。
60        echo "  エラーコード: " . $e->getCode() . " (int型) - UnhandledMatchError::code プロパティ\n";
61        echo "  発生ファイル: " . $e->getFile() . "\n";
62        echo "  発生行: " . $e->getLine() . "\n";
63    }
64
65    echo "\n--- デモンストレーション終了 ---\n";
66}
67
68// スクリプトの実行
69demonstrateUnhandledMatchErrorHandling();

PHP 8で新たに導入されたmatch式は、複数の条件分岐を分かりやすく記述するための構文です。しかし、このmatch式に、与えられた値に対応する処理（ケース）が一つも記述されていない場合、UnhandledMatchErrorというエラーが発生します。このエラーは、プログラムが予期しない入力に対して適切な処理を定義できていないことを示しており、コードの網羅性をチェックする「php code checker」の観点からも重要な情報となります。

UnhandledMatchErrorが発生した際、そのエラーオブジェクトが持つcodeプロパティ（またはgetCode()メソッドを通じて）を利用することで、エラーに関する整数値を取得できます。このcodeプロパティは引数を必要とせず、エラーの識別や記録に用いられるint型の値を返します。

提供されたサンプルコードでは、getStatusMessage関数内でmatch式にあえて未定義のケース（ステータス3）を作ることでUnhandledMatchErrorを発生させています。そして、demonstrateUnhandledMatchErrorHandling関数において、try-catchブロックでこのエラーを捕捉し、捕捉したエラーオブジェクトから$e->getCode()を使ってエラーコード（int型）を取り出し、表示する具体的な方法を示しています。これにより、システムエンジニアがエラー発生時に必要な情報を取得し、適切なデバッグやログ記録を行うための基礎を学ぶことができます。