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

Copy
1<?php
2
3/**
4 * ファイルの存在を確認し、内容を読み込むクラス
5 */
6class SafeFileReader
7{
8    /**
9     * 指定されたパスのファイル内容を安全に読み込みます。
10     *
11     * @param string $filePath 読み込むファイルのパス
12     * @return string ファイルの内容
13     * @throws RuntimeException ファイルが存在しないか、読み込めない場合にスローされます
14     */
15    public function readFile(string $filePath): string
16    {
17        // file_exists() を使って、処理を行う前にファイルの存在を確認します。
18        // これにより、存在しないファイルにアクセスしようとしてエラーが発生するのを防ぎます。
19        if (!file_exists($filePath)) {
20            // ファイルが存在しない場合は、例外をスローして処理を中断します。
21            throw new RuntimeException("エラー: ファイルが見つかりません。 Path: {$filePath}");
22        }
23
24        // ファイルが存在する場合、内容を読み込みます。
25        // file_get_contents() は失敗した場合に false を返すため、エラーハンドリングを行います。
26        $content = file_get_contents($filePath);
27        if ($content === false) {
28            throw new RuntimeException("エラー: ファイルの読み込みに失敗しました。 Path: {$filePath}");
29        }
30
31        return $content;
32    }
33}
34
35// --- 以下、実行サンプル ---
36
37$reader = new SafeFileReader();
38// 存在しないファイルパスを指定
39$nonExistentFile = 'path/to/non_existent_file.txt';
40
41try {
42    echo "--- 存在しないファイル '{$nonExistentFile}' の読み込みを試みます ---" . PHP_EOL;
43    $reader->readFile($nonExistentFile);
44} catch (RuntimeException $e) {
45    // 例外がスローされた場合、catchブロックで捕捉します。
46    echo "例外がキャッチされました！" . PHP_EOL;
47    echo $e->getMessage() . PHP_EOL;
48    
49    // $e->getFile() は、例外がスローされたファイル名を取得します。
50    // (リファレンス情報の UnderflowException も Throwable を継承しているため同じメソッドを持ちます)
51    echo "例外発生ファイル: " . $e->getFile() . PHP_EOL;
52    echo "例外発生ライン: " . $e->getLine() . "行目" . PHP_EOL;
53} finally {
54    echo PHP_EOL . "--- 処理を終了します ---" . PHP_EOL;
55}

このサンプルコードは、file_exists() 関数を利用して、ファイルの存在を安全に確認してから読み込む手順を示しています。プログラムがファイルにアクセスする際、対象のファイルが存在しないとエラーが発生する原因となります。file_exists() は、引数で指定されたパスにファイルやディレクトリが存在するかを調べ、存在すれば true、しなければ false を返す関数です。これを利用することで、処理を実行する前にファイルの存在を確認し、エラーを未然に防ぐことができます。

コード内の readFile メソッドでは、まず file_exists() でファイルの有無をチェックしています。もしファイルが存在しない場合、throw new RuntimeException() によって意図的に例外（エラー）を発生させ、処理を中断します。

実行部分では try...catch 構文が使われています。try ブロック内でエラーが発生する可能性のある処理を実行し、もし例外がスローされると catch ブロックでそれを捕捉します。捕捉された例外の情報は変数 $e に格納されます。$e->getMessage() はエラーメッセージを、$e->getLine() はエラーが発生した行番号を返します。そして $e->getFile() は、例外がスローされたファイル自身のパスを文字列として返します。これは、リファレンス情報にある UnderflowException の file プロパティが示す役割と同様に、エラー発生箇所の特定に役立ちます。

Copy
1<?php
2
3declare(strict_types=1);
4
5/**
6 * 指定されたファイルパスの内容を読み込み、処理します。
7 *
8 * この関数は、`file_get_contents()` を使ってファイルの内容を取得します。
9 * もしファイルの内容が空だった場合、処理が続行不可能とみなし、
10 * `UnderflowException` をスローします。
11 * これにより、空のデータソースを扱おうとした際のエラー処理を模倣します。
12 *
13 * @param string $filepath 読み込むファイルのパス
14 * @return void
15 * @throws UnderflowException ファイルの内容が空の場合
16 * @throws RuntimeException   ファイルの読み込みに失敗した場合
17 */
18function processFileData(string $filepath): void
19{
20    // `file_get_contents()` でファイルの内容を文字列として取得します。
21    // @演算子はファイルが存在しない場合などのWarning(警告)を抑制します。
22    $content = @file_get_contents($filepath);
23
24    if ($content === false) {
25        // file_get_contents() が false を返した場合、ファイルの読み込みに失敗しています。
26        throw new RuntimeException("ファイル '{$filepath}' の読み込みに失敗しました。");
27    }
28
29    if ($content === '') {
30        // ファイルの内容が空文字列の場合、UnderflowExceptionをスローします。
31        throw new UnderflowException("ファイル '{$filepath}' は空のため、処理できません。");
32    }
33
34    echo "ファイルの内容の処理に成功しました。\n";
35    echo $content;
36}
37
38// --- メインの実行部分 ---
39
40// テスト用に、中身が空のファイルを作成します。
41$emptyFilename = 'empty_test_file.txt';
42file_put_contents($emptyFilename, '');
43
44try {
45    echo "--- '{$emptyFilename}' の処理を開始します ---\n";
46    processFileData($emptyFilename);
47} catch (UnderflowException $e) {
48    // processFileData() でスローされた UnderflowException をここで捕捉します。
49    echo "エラー: 予期せぬ状態になりました。\n";
50
51    // getMessage(): 例外に設定されたエラーメッセージを取得します。
52    echo "メッセージ: " . $e->getMessage() . "\n";
53
54    // getFile(): 例外が発生したPHPスクリプトのフルパスを取得します。
55    // これがリファレンスにある 'file' プロパティに該当する情報です。
56    echo "発生ファイル: " . $e->getFile() . "\n";
57
58    // getLine(): 例外がスローされたコードの行番号を取得します。
59    echo "発生行: " . $e->getLine() . "\n";
60} finally {
61    // tryブロックやcatchブロックの処理後、必ず実行される処理です。
62    // テスト用に作成したファイルを削除して、後片付けをします。
63    if (file_exists($emptyFilename)) {
64        unlink($emptyFilename);
65    }
66    echo "--- 処理を終了します ---\n";
67}

このサンプルコードは、ファイルの内容が空であるという予期せぬ状態が発生した際に UnderflowException を使用する例を示しています。UnderflowException は、空のコンテナから値を取り出そうとするなど、処理の続行が不可能な状態を表すための例外です。

コード内の processFileData 関数は、引数 $filepath で指定されたファイルを file_get_contents を使って読み込みます。もしファイルの中身が空文字列だった場合、この関数は UnderflowException を意図的に発生させます。

メイン処理では try...catch 構文でこの例外を捕捉しています。catch ブロックで受け取った例外オブジェクト（変数 $e）からは、エラーに関する詳細な情報を取得できます。$e->getFile() メソッドを呼び出すと、例外が発生したPHPスクリプトのファイルパスが戻り値として文字列で返されます。これがリファレンスで示されている file プロパティの情報に該当し、エラーがどのファイルで起きたかを特定する際に非常に役立ちます。このように、例外オブジェクトが持つファイルパスや行番号などの情報を利用することで、問題の発見と修正を効率的に行うことができます。