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

Copy
1<?php
2
3/**
4 * UnhandledMatchError の file プロパティ（エラー発生ファイルパス）を
5 * 示すサンプルコードです。
6 * `file_get_contents` を使用してファイルの内容を読み込み、その内容を
7 * `match` 式で処理する際に、意図的にハンドルされないケースを発生させます。
8 */
9function demonstrateUnhandledMatchErrorFileProperty(): void
10{
11    // UnhandledMatchErrorを発生させるための設定を一時ファイルに書き込みます。
12    // このファイルの内容がmatch式で対応するケースを持たないように設定します。
13    $tempFilePath = 'temp_config.txt';
14    $unhandledAction = 'unsupported_action'; // match式で処理されない値
15
16    // 一時ファイルに内容を書き込む
17    file_put_contents($tempFilePath, $unhandledAction);
18
19    try {
20        echo "--- 処理開始 ---\n";
21        echo "ファイル '{$tempFilePath}' の内容を読み込み、match式で処理します。\n\n";
22
23        // `file_get_contents` を使用してファイルの内容を読み込みます。
24        $action = file_get_contents($tempFilePath);
25
26        // PHP 8 の `match` 式を使用します。
27        // 変数 $action の値が、定義されたどのアーム（case）にも一致しない場合、
28        // `UnhandledMatchError` がスローされます。
29        $message = match ($action) {
30            'display_info' => '情報を表示します。',
31            'execute_command' => 'コマンドを実行します。',
32            // 'unsupported_action' に対応するアームがないため、
33            // ここで UnhandledMatchError が発生します。
34        };
35
36        echo "結果: " . $message . "\n"; // この行は実行されません
37    } catch (UnhandledMatchError $e) {
38        echo "--- エラー捕捉 ---\n";
39        echo "UnhandledMatchError を捕捉しました！\n";
40        // `getFile()` メソッドは、このエラーが発生したPHPスクリプトのファイルパスを返します。
41        echo "エラー発生ファイル: " . $e->getFile() . "\n";
42        echo "エラーメッセージ: " . $e->getMessage() . "\n";
43    } finally {
44        // 作成した一時ファイルを削除し、クリーンアップします。
45        if (file_exists($tempFilePath)) {
46            unlink($tempFilePath);
47            echo "\n一時ファイル '{$tempFilePath}' を削除しました。\n";
48        }
49        echo "--- 処理終了 ---\n";
50    }
51}
52
53// デモンストレーション関数を実行します。
54demonstrateUnhandledMatchErrorFileProperty();

このサンプルコードは、PHP 8で導入されたUnhandledMatchErrorクラスが持つfileプロパティ（getFile()メソッドでアクセス）の挙動を説明します。UnhandledMatchErrorは、PHP 8のmatch式を使用する際に、与えられた値に対応するケース（アーム）が一つも見つからなかった場合に発生するエラーです。

コードでは、まずfile_put_contents関数を使って一時ファイルに「unsupported_action」という文字列を書き込みます。次に、file_get_contents関数でこのファイルの内容を読み込み、その結果をmatch式に渡します。しかし、match式には「unsupported_action」に対応するケースが定義されていないため、意図的にUnhandledMatchErrorが発生します。

try-catchブロックでこのエラーを捕捉した後、$e->getFile()メソッドを呼び出すことで、エラーが実際に発生したPHPスクリプトのファイルパスを文字列として取得し、画面に表示しています。getFile()メソッドは引数を取らず、エラー発生元の正確なファイルパスをstring型で返します。これは、プログラムのエラー原因を特定し、デバッグする際に非常に重要な情報となります。

Copy
1<?php
2
3// このサンプルコードは、PHP 8で導入されたUnhandledMatchErrorを意図的に発生させ、
4// そのエラー情報を捕捉し、file_put_contents関数を使ってログファイルに記録する方法を示します。
5
6// エラーログを保存するファイルのパスを定義します。
7// __DIR__ は現在のスクリプトがあるディレクトリを指します。
8$logFilePath = __DIR__ . '/unhandled_match_error_log.txt';
9
10try {
11    // UnhandledMatchErrorを発生させるための値を定義します。
12    // この値（4）に対応するcaseがなく、デフォルトのアームもありません。
13    $status = 4;
14
15    // PHP 8のmatch式を使用します。
16    // $statusがどのcaseにもマッチせず、defaultアームもないため、
17    // ここでUnhandledMatchErrorがスローされます。
18    $result = match ($status) {
19        1 => 'Pending',
20        2 => 'Processing',
21        3 => 'Completed',
22        // '4' に対応するcaseや 'default' アームがないため、エラーが発生します。
23    };
24
25    // 上記でエラーがスローされるため、この行は実行されません。
26    echo "Match result: " . $result . PHP_EOL;
27
28} catch (UnhandledMatchError $e) {
29    // UnhandledMatchErrorを捕捉します。
30    echo "UnhandledMatchErrorを捕捉しました！" . PHP_EOL;
31
32    // 捕捉したエラーオブジェクトから、エラーが発生したファイルパスを取得します。
33    // これは`UnhandledMatchError`クラスの`file`プロパティ（実際にはException::getFile()メソッド）です。
34    $errorOccurredFile = $e->getFile();
35
36    // その他の有用なエラー情報も取得します。
37    $errorMessage = $e->getMessage();
38    $errorLine = $e->getLine();
39
40    // ログファイルに書き込む内容を準備します。
41    $logContent = "タイムスタンプ: " . date('Y-m-d H:i:s') . PHP_EOL;
42    $logContent .= "エラータイプ: " . get_class($e) . PHP_EOL;
43    $logContent .= "メッセージ: " . $errorMessage . PHP_EOL;
44    $logContent .= "エラーが発生したファイル: " . $errorOccurredFile . PHP_EOL;
45    $logContent .= "行番号: " . $errorLine . PHP_EOL;
46    $logContent .= "----------------------------------------" . PHP_EOL;
47
48    // file_put_contents関数を使用して、準備したエラー情報をログファイルに書き込みます。
49    // FILE_APPENDフラグを指定することで、既存のファイル内容を上書きせずに、
50    // 新しい内容をファイルの末尾に追加します。
51    if (file_put_contents($logFilePath, $logContent, FILE_APPEND) !== false) {
52        echo "エラー詳細をログファイルに記録しました: " . $logFilePath . PHP_EOL;
53    } else {
54        echo "エラーログファイルへの書き込みに失敗しました: " . $logFilePath . PHP_EOL;
55    }
56}
57
58// このスクリプトを実行すると、`unhandled_match_error_log.txt`というファイルが
59// スクリプトと同じディレクトリに生成され、エラー情報が記録されます。
60

このサンプルコードは、PHP 8で導入されたUnhandledMatchErrorというエラーを捕捉し、その詳細をログファイルに記録する方法を示しています。UnhandledMatchErrorは、match式において、どのcaseにもマッチせず、かつdefaultアームが定義されていない場合に発生します。

コードでは、意図的にmatch式でエラーを発生させ、try-catchブロックでこのUnhandledMatchErrorを捕捉しています。エラーが捕捉されると、エラーオブジェクト$eから様々な情報を取得できます。その中でも、リファレンス情報にあるfileプロパティ（実際にはgetFile()メソッドを通じてアクセス）は、エラーが発生したPHPスクリプトのフルパスを文字列として返します。このメソッドは引数を必要としません。

取得したエラー情報（発生ファイル、メッセージ、行番号など）は、変数$logContentにまとめられます。その後、file_put_contents関数を使って、この情報をunhandled_match_error_log.txtというファイルに書き込んでいます。file_put_contentsは、第一引数に書き込むファイルのパス、第二引数に書き込む内容、第三引数に書き込みモード（ここではFILE_APPENDで追記）を受け取ります。ファイルへの書き込みが成功すると書き込まれたバイト数を、失敗するとfalseを戻り値として返します。このようにして、発生したエラーの記録を行い、デバッグやシステム運用に役立てることが可能です。

Copy
1<?php
2
3/**
4 * この関数は、意図的に UnhandledMatchError を発生させ、そのエラーオブジェクトから
5 * 発生元のファイルパスを取得し、file_exists 関数でそのファイルの存在を確認するデモンストレーションです。
6 *
7 * UnhandledMatchError は PHP 8 で導入されたエラーで、match 式が全ての可能な値を網羅していない場合に発生します。
8 */
9function demonstrateUnhandledMatchErrorFileCheck(): void
10{
11    echo "--- UnhandledMatchError と file_exists の連携デモンストレーションを開始します ---" . PHP_EOL;
12
13    // 意図的に UnhandledMatchError を発生させるための値。
14    // match 式には '3' に対応するケースがないため、エラーが発生します。
15    $input_value = 3;
16
17    try {
18        echo "match 式を実行します。現在の値: {$input_value}" . PHP_EOL;
19        
20        // この match 式は、'$input_value' が '3' の場合に UnhandledMatchError を発生させます。
21        $result = match ($input_value) {
22            1 => "値は1です",
23            2 => "値は2です",
24            // '3' のケースがないため、ここに到達した時点でエラーとなります。
25        };
26        // エラーが発生した場合、この行は実行されません。
27        echo "match 式の実行結果: " . $result . PHP_EOL; 
28
29    } catch (UnhandledMatchError $e) {
30        echo "UnhandledMatchError が捕捉されました。" . PHP_EOL;
31
32        // UnhandledMatchError オブジェクトの 'file' プロパティから、
33        // エラーが発生したスクリプトのファイルパスを取得します。
34        $errorFilePath = $e->file;
35        echo "エラーが発生したファイルパス: '{$errorFilePath}'" . PHP_EOL;
36
37        // 取得したファイルパスが実際にシステム上に存在するかどうかを
38        // file_exists 関数を使って確認します。
39        if (file_exists($errorFilePath)) {
40            echo "→ このファイルはシステム上に存在します。" . PHP_EOL;
41        } else {
42            // UnhandledMatchError::file が返すファイルは常に存在するため、このメッセージは通常表示されません。
43            echo "→ このファイルはシステム上に存在しません。(異常な状態です)" . PHP_EOL;
44        }
45
46        echo "エラーメッセージ: " . $e->getMessage() . PHP_EOL;
47
48    } finally {
49        echo "--- デモンストレーションを終了します ---" . PHP_EOL;
50    }
51}
52
53// 上記のデモンストレーション関数を実行します。
54demonstrateUnhandledMatchErrorFileCheck();

このPHPサンプルコードは、PHP 8で導入されたUnhandledMatchErrorが発生した際に、そのエラーオブジェクトからエラー発生元のファイルパスを取得し、file_exists関数を使ってそのファイルの存在を確認する方法を示しています。

UnhandledMatchErrorは、match式が取り得る全ての値を網羅していない場合に発生するエラーです。このコードでは、match式に未定義のケース（値3）を渡すことで、意図的にこのエラーを発生させています。

try-catchブロックでUnhandledMatchErrorを捕捉すると、捕捉されたエラーオブジェクト$eを通じて、エラーの詳細にアクセスできます。特に$e->fileプロパティは、エラーが発生したスクリプトのフルパスを文字列（string）として返します。このプロパティは引数を取りません。

取得したファイルパスは、file_exists関数に渡されます。file_exists関数は、引数として受け取ったファイルパスが実際にシステム上に存在するかどうかを調べ、存在すればtrue、存在しなければfalseという真偽値（bool）を返します。このデモンストレーションでは、UnhandledMatchError::fileプロパティが常に有効なファイルパスを返すため、「このファイルはシステム上に存在します」という結果が表示されます。

この例は、エラー発生時にその原因となったファイルパスをプログラムから特定し、その情報に基づいて処理を行う実践的な方法を示しています。

Copy
1<?php
2
3/**
4 * PHP 8 の UnhandledMatchError を意図的に発生させ、
5 * そのエラー発生元のファイルのパスとサイズを報告する関数です。
6 *
7 * この関数は、以下の要素を組み合わせて示します。
8 * 1. PHP 8 で導入された `match` 式の網羅性チェック。
9 * 2. `UnhandledMatchError` の捕捉と、そのエラーオブジェクトの `file` プロパティ（エラー発生元ファイルのパス）の利用。
10 * 3. 取得したファイルパスを用いて、`filesize()` 関数でファイルのサイズを取得する方法。
11 *
12 * システムエンジニアを目指す初心者の方が、エラー処理とファイル情報取得の基本を理解するのに役立ちます。
13 *
14 * @param mixed $value `match` 式に渡される値。意図的に `UnhandledMatchError` を発生させるため、
15 *                     `match` 式内で定義されていないケースの値を渡すことを想定しています。
16 * @return string エラー情報と、エラーが発生したファイルのサイズに関する詳細なメッセージを返します。
17 */
18function demonstrateErrorFileAndSize(mixed $value): string
19{
20    try {
21        // PHP 8 の 'match' 式を使用。
22        // ここでは、指定された $value が 'red' または 'blue' のいずれでもない場合、
23        // かつ `default` ケースも存在しないため、`UnhandledMatchError` がスローされます。
24        $colorDescription = match ($value) {
25            'red' => '情熱的な赤色です。',
26            'blue' => '落ち着いた青色です。',
27            // 'default' => '不明な色です。' // この行をコメントアウトすることで、UnhandledMatchError を発生させます。
28        };
29
30        // UnhandledMatchError が発生しなかった場合、この行が実行されます。
31        return "マッチ処理が成功しました: " . $colorDescription . PHP_EOL;
32
33    } catch (UnhandledMatchError $e) {
34        // `UnhandledMatchError` をキャッチし、エラー情報を処理します。
35        $output = "--- UnhandledMatchError が発生しました ---" . PHP_EOL;
36        $output .= "エラーメッセージ: " . $e->getMessage() . PHP_EOL;
37
38        // `UnhandledMatchError` オブジェクトの `file` プロパティを利用して、
39        // エラーが発生したスクリプトのファイルパスを取得します。
40        $errorFilePath = $e->file;
41        $output .= "エラーが発生したファイル: " . $errorFilePath . PHP_EOL;
42
43        // 取得したファイルパスが存在するか確認し、`filesize()` 関数でそのファイルのサイズを取得します。
44        if (file_exists($errorFilePath)) {
45            // `filesize()` 関数は、指定されたファイルのサイズをバイト単位で返します。
46            $sizeInBytes = filesize($errorFilePath);
47
48            if ($sizeInBytes !== false) {
49                // ファイルサイズが正常に取得できた場合
50                $output .= "エラーが発生したファイルのサイズ: " . $sizeInBytes . " バイト" . PHP_EOL;
51                // より人間が読みやすい形式 (例: キロバイト) に変換して表示することも可能です。
52                // $output .= " (" . round($sizeInBytes / 1024, 2) . " KB)" . PHP_EOL;
53            } else {
54                // `filesize()` が `false` を返した場合（例: 読み取り権限がない、ファイルが壊れている）
55                $output .= "エラーが発生したファイルのサイズ取得に失敗しました。" . PHP_EOL;
56            }
57        } else {
58            // `file_exists()` が `false` を返した場合（例: パスが無効、ファイルが削除された）
59            $output .= "エラーが発生したファイルが見つかりません: " . $errorFilePath . PHP_EOL;
60        }
61        return $output;
62    }
63}
64
65// --- サンプルコードの実行 ---
66
67// `match` 式で定義されていない値を渡すことで、`UnhandledMatchError` を意図的に発生させます。
68echo demonstrateErrorFileAndSize('green');
69
70echo PHP_EOL;
71
72// (参考) もし 'red' のような定義済みの値を渡した場合、エラーは発生しません。
73// echo demonstrateErrorFileAndSize('red');
74
75?>

このサンプルコードは、PHP 8で導入されたmatch式の網羅性チェックによって発生するUnhandledMatchErrorを処理し、さらにエラーが発生したファイルのパスとそのサイズを取得する方法を示しています。

demonstrateErrorFileAndSize関数は、引数$valueを受け取ります。この関数内ではmatch式が使用されており、$valueが定義された'red'や'blue'以外の値である場合、UnhandledMatchErrorが意図的に発生します。

このエラーはtry-catchブロックで捕捉されます。捕捉されたUnhandledMatchErrorオブジェクトのfileプロパティは、エラーが発生したファイルのパス（string型）を返します。このプロパティは引数を持ちません。コードではこのfileプロパティを利用してファイルパスを取得し、file_exists()関数でファイルの存在を確認した後、filesize()関数を用いてそのファイルのサイズをバイト単位で取得しています。最後に、これらのエラー情報とファイルサイズを詳細なメッセージとして文字列で返します。

このコードは、エラー処理の基本と、エラー発生元のファイル情報をプログラム的に取得・活用する方法を、初心者の方にも分かりやすく解説することを目的としています。