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

Copy
1<?php
2
3/**
4 * 指定されたファイルの存在を確認し、コンテンツを読み込もうとします。
5 *
6 * この関数は、`file_exists()` を使ってファイルの存在をチェックします。
7 * ファイルが存在しない場合、`UnexpectedValueException` をスローします。
8 * この例外は、値が期待した条件（この場合はファイルの存在）を満たさない場合に適しています。
9 *
10 * @param string $filename チェックおよび読み込み対象のファイルパス
11 *
12 * @return void
13 *
14 * @throws UnexpectedValueException ファイルが存在しない場合にスローされる
15 */
16function processFile(string $filename): void
17{
18    // キーワード `file_exists` を使用して、ファイルの存在を確認します。
19    if (!file_exists($filename)) {
20        // ファイルが存在しないという予期せぬ状態のため、UnexpectedValueExceptionをスローします。
21        throw new UnexpectedValueException("ファイルが見つかりません: {$filename}");
22    }
23
24    // ファイルが存在する場合の処理（この例ではメッセージを表示）
25    echo "ファイル '{$filename}' の処理を開始します。" . PHP_EOL;
26    // ここで file_get_contents() などのファイル処理を続けます。
27}
28
29// 存在しないファイルパスを意図的に指定します。
30$nonExistentFile = 'path/to/non_existent_file.txt';
31
32try {
33    // ファイル処理関数を呼び出します。
34    processFile($nonExistentFile);
35} catch (UnexpectedValueException $e) {
36    // processFile関数からスローされた例外をここで捕捉します。
37    echo "エラーが発生しました。" . PHP_EOL;
38    echo "メッセージ: " . $e->getMessage() . PHP_EOL;
39
40    // Exceptionクラスが持つ `getFile()` メソッドで、例外がスローされたファイル名を取得します。
41    // これはリファレンスの `file` プロパティに対応する公開メソッドです。
42    echo "例外発生ファイル: " . $e->getFile() . PHP_EOL;
43    echo "例外発生行: " . $e->getLine() . PHP_EOL;
44}

このPHPサンプルコードは、指定されたファイルが存在しない場合に UnexpectedValueException という種類の例外（エラー）を発生させる例です。

processFile関数は、PHPの組み込み関数 file_exists() を使用して、引数で渡されたファイルパスの存在を確認します。ファイルが存在しないという予期せぬ状況が発生した場合、throwキーワードを使ってUnexpectedValueExceptionを意図的に発生させます。

try...catch構文は、この発生した例外を捕捉するために使われます。catchブロックでは、捕捉した例外オブジェクト $e を使ってエラーに関する情報を取得できます。

リファレンスにあるfileプロパティは、この例外オブジェクトが持つ情報の一つで、例外がどのファイルで発生したかを示します。このプロパティの値は、$e->getFile()というメソッドを呼び出すことで取得できます。getFile()メソッドは引数を取らず、戻り値として例外が発生したPHPスクリプトのファイルパスを文字列で返します。これにより、プログラムのどこで問題が起きたのかを正確に特定でき、デバッグ作業に役立ちます。getMessage()やgetLine()と合わせて使うことで、より詳細なエラー情報を得ることが可能です。

Copy
1<?php
2
3/**
4 * ファイルからJSON設定を読み込み、内容を配列として返します。
5 *
6 * この関数は、指定されたファイルパスから設定を読み込もうとします。
7 * ファイルの内容が不正なJSON形式であった場合、UnexpectedValueException をスローします。
8 *
9 * @param string $filePath 設定ファイルのパス
10 * @return array<string, mixed> デコードされた設定データ
11 * @throws RuntimeException ファイルが存在しない、または読み込みに失敗した場合
12 * @throws UnexpectedValueException JSONのパースに失敗した場合
13 */
14function loadConfiguration(string $filePath): array
15{
16    // file_get_contents でファイルの内容を文字列として取得します。
17    // @演算子は、ファイルが存在しない場合などのWarningを抑制し、後続のif文でエラー処理を一元化します。
18    $jsonContent = @file_get_contents($filePath);
19
20    if ($jsonContent === false) {
21        throw new RuntimeException("設定ファイル '{$filePath}' が読み込めませんでした。");
22    }
23
24    // JSONをデコードします。JSON_THROW_ON_ERRORフラグにより、パース失敗時にJsonExceptionがスローされます。
25    try {
26        return json_decode($jsonContent, true, 512, JSON_THROW_ON_ERROR);
27    } catch (JsonException $e) {
28        // JsonExceptionをキャッチし、より具体的な UnexpectedValueException をスローします。
29        // これにより、アプリケーション固有の例外処理が可能になります。
30        throw new UnexpectedValueException(
31            "設定ファイル '{$filePath}' の形式が不正です。",
32            0,
33            $e
34        );
35    }
36}
37
38// --- 以下、サンプルコードの実行部分 ---
39
40// わざと不正な形式のJSONファイルを作成して、例外を発生させます。
41$invalidConfigFile = 'config.json';
42file_put_contents($invalidConfigFile, '{"user": "test", "host": "localhost",}'); // 末尾のカンマが構文エラー
43
44try {
45    // 設定ファイルの読み込みを試みます。
46    $config = loadConfiguration($invalidConfigFile);
47    echo "設定が正常に読み込まれました。\n";
48    print_r($config);
49} catch (UnexpectedValueException $e) {
50    // 例外を捕捉し、UnexpectedValueExceptionが持つプロパティから情報を取得して表示します。
51    // $e->getFile() は、例外がスローされたファイルへのフルパスを返します。
52    echo "エラー: " . $e->getMessage() . "\n";
53    echo "発生ファイル: " . $e->getFile() . "\n";
54    echo "発生行: " . $e->getLine() . "\n";
55} catch (RuntimeException $e) {
56    echo "実行時エラー: " . $e->getMessage() . "\n";
57} finally {
58    // 実行後、作成した一時ファイルを削除します。
59    if (file_exists($invalidConfigFile)) {
60        unlink($invalidConfigFile);
61    }
62}

このサンプルコードは、JSON形式の設定ファイルを読み込む処理で、ファイルの内容が不正な形式だった場合に UnexpectedValueException という例外を発生させる例です。

UnexpectedValueException オブジェクトが持つ file プロパティは、例外がスローされた（発生した）PHPスクリプトファイルのフルパスを文字列として保持しています。このプロパティに引数はなく、戻り値としてファイルパスの文字列を返します。通常、この値は getFile() メソッドを呼び出すことで取得します。

サンプルコードでは、わざと構文エラーのあるJSONファイルを作成し、loadConfiguration関数で読み込ませています。この関数はJSONの解析に失敗すると、アプリケーション固有のエラーとして UnexpectedValueException をスローします。try...catch 構文でこの例外を捕捉し、$e->getFile() を実行することで、エラーが発生したファイル名を取得して表示しています。

このように file プロパティは、getLine() メソッド（行番号を取得）などと組み合わせることで、プログラムのどこで問題が起きたのかを正確に特定するために役立ち、エラーの原因調査（デバッグ）を容易にします。