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

Copy
1<?php
2
3/**
4 * UnhandledMatchError::getFile() メソッドのサンプルコード。
5 *
6 * この関数は、PHP 8 で導入された match 式において、
7 * 網羅されていないケースが発生した場合にスローされる UnhandledMatchError を意図的に発生させ、
8 * そのエラーオブジェクトから getFile() メソッドを使って
9 * エラーが発生したスクリプトのファイルパスを取得する方法を示します。
10 *
11 * @param string $input 評価する値。'apple' または 'banana' 以外の値でエラーが発生します。
12 * @return string エラー発生時のファイルパス、または match 式の正常な結果を示す文字列。
13 */
14function demonstrateUnhandledMatchErrorGetFile(string $input): string
15{
16    try {
17        // match 式は厳密で、全ての可能な値に対してケースが定義されている必要があります。
18        // ここでは 'grape' という値が入力された場合、どのケースにも一致しないため
19        // UnhandledMatchError がスローされるように意図的に記述されています。
20        $result = match ($input) {
21            'apple' => '選択されたのはリンゴです。',
22            'banana' => '選択されたのはバナナです。',
23            // 'grape' など、上記のどれにも当てはまらない値が来た場合に
24            // UnhandledMatchError が発生するように、他のケースを意図的に省略しています。
25        };
26
27        return "match 式は正常に処理されました: " . $result;
28
29    } catch (UnhandledMatchError $e) {
30        // UnhandledMatchError を捕捉した場合
31        // Throwable インターフェースを実装するクラス（UnhandledMatchError も含む）は
32        // getFile() メソッドを持ち、エラーが発生したソースファイルのパスを返します。
33        $filePath = $e->getFile();
34        $message = $e->getMessage();
35
36        return "UnhandledMatchError が発生しました。\n"
37             . "エラーメッセージ: " . $message . "\n"
38             . "エラーが発生したファイルパス: " . $filePath;
39
40    } catch (Throwable $e) {
41        // その他の予期しないエラーを捕捉する一般的なケース
42        return "予期せぬエラーが発生しました: " . $e->getMessage();
43    }
44}
45
46// --- サンプル実行 ---
47
48// 1. match 式が正常に処理されるケース
49echo "--- 正常な入力の場合 ---\n";
50echo demonstrateUnhandledMatchErrorGetFile('apple') . "\n\n";
51
52// 2. UnhandledMatchError が発生するケース
53// 'grape' は match 式のどのケースにも対応していないため、UnhandledMatchError がスローされます。
54echo "--- UnhandledMatchError が発生する入力の場合 ---\n";
55echo demonstrateUnhandledMatchErrorGetFile('grape') . "\n";
56
57?>

PHP 8で導入されたmatch式は、複数の条件に対する厳密な分岐処理を行うための機能です。switch文と異なり、match式では全ての可能な値に対してケースを定義する必要があります。もし、入力値が定義されているどのケースにも一致しない場合、PHPはUnhandledMatchErrorをスローし、プログラムの実行を中断します。

UnhandledMatchErrorクラスのgetFile()メソッドは、このUnhandledMatchErrorが発生した際に、具体的にどのファイルでエラーが起きたのかを特定するためのファイルパス（文字列）を返します。このメソッドは引数を必要としません。

サンプルコードでは、demonstrateUnhandledMatchErrorGetFile関数内でmatch式を使用し、意図的に'grape'のような未定義の値を入力することでUnhandledMatchErrorを発生させています。try-catchブロックでこのエラーを捕捉し、捕捉したエラーオブジェクト$eに対して$e->getFile()を呼び出すことで、エラーが発生したスクリプトのファイルパスを取得し表示しています。'apple'のような定義済みの値が入力された場合はエラーは発生せず、match式が正常に処理される様子も示されています。これにより、エラー発生時のファイルパス取得の仕組みが明確に理解できます。

Copy
1<?php
2
3/**
4 * 指定されたディレクトリ内の、指定されたパターンに一致するファイルリストを取得します。
5 *
6 * @param string $directoryPath 検索対象のディレクトリパス
7 * @param string $pattern       ファイル検索パターン (例: '*.php', '*.txt', '*.*')
8 * @return array<string>         パターンに一致したファイルの絶対パスの配列。
9 *                                エラー発生時やファイルが見つからない場合は空の配列を返します。
10 */
11function getFileList(string $directoryPath, string $pattern = '*'): array
12{
13    // ディレクトリが存在し、読み取り可能かを確認します。
14    if (!is_dir($directoryPath) || !is_readable($directoryPath)) {
15        echo "エラー: 指定されたディレクトリ '{$directoryPath}' が存在しないか、読み取り権限がありません。\n";
16        return [];
17    }
18
19    // glob関数を使用して、指定されたパターンに一致するファイルのパスを検索します。
20    // rtrim($directoryPath, '/\\') でパスの末尾のスラッシュやバックスラッシュを削除し、
21    // DIRECTORY_SEPARATOR でOSに応じた区切り文字を追加しています。
22    $fullPathPattern = rtrim($directoryPath, '/\\') . DIRECTORY_SEPARATOR . $pattern;
23    $files = glob($fullPathPattern);
24
25    // glob関数が失敗した場合（例: システムエラーなど）
26    if ($files === false) {
27        echo "エラー: ディレクトリ '{$directoryPath}' でファイル検索に失敗しました。\n";
28        return [];
29    }
30
31    // 取得したファイルのパスの配列を返します。
32    return $files;
33}
34
35// --- 使用例 ---
36
37// 現在のスクリプトがあるディレクトリを検索対象とします。
38$targetDirectory = __DIR__;
39
40echo "--- 現在のディレクトリ ({$targetDirectory}) 内のPHPファイル一覧 ---\n";
41$phpFiles = getFileList($targetDirectory, '*.php');
42
43if (!empty($phpFiles)) {
44    foreach ($phpFiles as $filePath) {
45        echo "- " . basename($filePath) . "\n"; // ファイル名のみ表示
46    }
47} else {
48    echo "PHPファイルは見つかりませんでした。\n";
49}
50
51echo "\n--- 現在のディレクトリ ({$targetDirectory}) 内のすべてのファイルとディレクトリ一覧 ---\n";
52// '.' や '..' を含まず、パターンに合致するもののみを返します。
53$allFilesAndDirs = getFileList($targetDirectory, '*');
54
55if (!empty($allFilesAndDirs)) {
56    foreach ($allFilesAndDirs as $filePath) {
57        // is_dir() でディレクトリかファイルを判定し、区別して表示することも可能です。
58        echo "- " . basename($filePath) . "\n"; // ファイル名またはディレクトリ名のみ表示
59    }
60} else {
61    echo "ファイルやディレクトリは見つかりませんでした。\n";
62}
63
64// 存在しないディレクトリを指定した場合の例
65echo "\n--- 存在しないディレクトリの例 ---\n";
66$nonExistentFiles = getFileList('/path/to/non/existent/directory', '*');
67// エラーメッセージは関数内で出力されます。
68
69?>

このPHPのサンプルコードは、特定のディレクトリ内から、指定されたパターンに一致するファイルの一覧を取得するgetFileList関数を定義しています。この関数は、システムエンジニアがディレクトリ内のファイルを操作する際に非常に役立ちます。

getFileList関数は二つの引数を取ります。一つ目の$directoryPathは、ファイルを検索する対象のディレクトリのパスを指定します。二つ目の$patternは、検索するファイル名のパターンを指定するもので、例えば'*.php'とすればPHPファイルのみを、'*'とすれば全てのファイルとディレクトリを対象とします。この引数は省略可能で、省略した場合は'*'が適用されます。

関数は、パターンに一致したファイルの絶対パスを文字列の配列として返します。指定されたディレクトリが存在しない、読み取り権限がない、またはファイルが見つからない場合は、空の配列を返してエラーを通知します。内部では、PHP標準のglob関数を利用してパターンマッチングを実行しており、事前にディレクトリの存在と読み取り権限も確認しています。

サンプルコードでは、現在実行中のスクリプトがあるディレクトリからPHPファイル一覧を取得する例や、全てのファイルおよびディレクトリの一覧を取得する例が示されています。また、存在しないディレクトリを指定した場合に、どのようにエラーが処理されるかについても確認できます。これにより、初心者の方でもファイルのリスト取得とエラーハンドリングの基本を学ぶことができます。

Copy
1<?php
2
3/**
4 * UnhandledMatchError を意図的に発生させ、
5 * そのエラーが発生したファイル名を取得するサンプルコード。
6 *
7 * この関数は、match 式が網羅的でない場合に発生する UnhandledMatchError を捕捉し、
8 * エラーが発生したスクリプトのファイルパスを表示します。
9 */
10function demonstrateUnhandledMatchErrorAndGetFile(): void
11{
12    try {
13        // UnhandledMatchError を発生させるための match 式
14        // 変数 $value が 'z' の場合、どのケースにもマッチせず UnhandledMatchError が発生します。
15        $value = 'z';
16        $result = match ($value) {
17            'a' => 'Case A',
18            'b' => 'Case B',
19            // ここに 'z' に対応するケースや default がないため、
20            // $value が 'z' の場合は UnhandledMatchError がスローされます。
21        };
22        // 上記の match 式でエラーが発生するため、この行は通常実行されません。
23        echo "Match result: " . $result . PHP_EOL;
24    } catch (UnhandledMatchError $e) {
25        // UnhandledMatchError を捕捉した場合の処理
26        echo "UnhandledMatchError が捕捉されました！" . PHP_EOL;
27        echo "エラーメッセージ: " . $e->getMessage() . PHP_EOL;
28
29        // エラーが発生したファイル名（パスを含む）を取得します。
30        // これはデバッグ時に、どのファイルで問題が起きたかを特定するのに役立ちます。
31        echo "エラー発生ファイル: " . $e->getFile() . PHP_EOL;
32    } catch (Throwable $e) {
33        // UnhandledMatchError 以外の予期せぬエラーも捕捉する場合
34        echo "予期せぬエラーが発生しました: " . $e->getMessage() . PHP_EOL;
35    }
36}
37
38// 関数を実行して動作を確認します。
39demonstrateUnhandledMatchErrorAndGetFile();

このサンプルコードは、PHP 8から導入されたmatch式において、予期せぬ値が与えられ、どの条件にも対応しない場合に発生するUnhandledMatchErrorというエラーを意図的に発生させ、そのエラーがどのファイルで発生したかを取得する方法を示しています。

match式は、指定された値に基づいて処理を分岐させる強力な構文ですが、もし与えられた値に対応するケースが一切定義されておらず、かつdefaultケースも存在しない場合、PHPはUnhandledMatchErrorをスローします。

このコードでは、try...catchブロックを用いてUnhandledMatchErrorを捕捉しています。エラーが捕捉されると、UnhandledMatchErrorオブジェクトのgetFile()メソッドが呼び出されます。このgetFile()メソッドは引数を一切必要とせず、エラーが発生したPHPスクリプトの完全なファイルパスを文字列として返します。

このように、getFile()メソッドを利用することで、プログラム実行中に発生したエラーの原因がどのファイルにあるのかを正確に特定でき、システム開発におけるデバッグ作業や問題解決を効率的に進める上で非常に有用です。