【PHP8.x】PSFS_ERR_FATAL定数の使い方

Copy
1<?php
2
3/**
4 * カスタムストリームフィルターを定義するクラス。
5 * PHPの標準機能であるストリームフィルターを拡張し、
6 * データが読み書きされる際に特定の処理を適用します。
7 *
8 * システムエンジニアを目指す初心者向けに、ストリームフィルターの基本的な動作と、
9 * `PSFS_PASS_ON` および `PSFS_ERR_FATAL` の定数の使い方を簡潔に示します。
10 */
11class MySimpleStreamFilter extends php_user_filter
12{
13    /**
14     * ストリームフィルターの主要な処理ロジック。
15     * 入力バケット (ストリームから読み込むデータ) を処理し、
16     * 出力バケット (ストリームに書き込むデータ) に変換されたデータを格納します。
17     *
18     * @param resource $in  入力バケットブリゲード（処理待ちのデータが含まれる）
19     * @param resource $out 出力バケットブリゲード（処理後のデータを格納する）
20     * @param int      $consumed 処理されたバイト数を格納する変数への参照
21     * @param bool     $closing  ストリームが閉じられている最中かどうか (PHP 8で追加された引数)
22     * @return int フィルターのステータスを表す定数。
23     *             - `PSFS_PASS_ON`: データが正常に処理され、次のフィルターまたは最終的な宛先に渡されるべき。
24     *             - `PSFS_ERR_FATAL`: フィルター処理中に回復不可能な致命的なエラーが発生した。
25     *             - `PSFS_FEED_ME`: フィルターは処理を続行するためにさらにデータが必要。
26     */
27    public function filter($in, $out, &$consumed, bool $closing)
28    {
29        while ($bucket = stream_bucket_make_writable($in)) {
30            // 入力バケットからデータを取得し、処理します。
31            $originalData = $bucket->data;
32
33            // 例: データ内の 'ERROR' という文字列を検出したら、致命的なエラーをシミュレート
34            if (str_contains(strtoupper($originalData), 'ERROR')) {
35                // PSFS_ERR_FATAL は、フィルターがデータの処理をこれ以上続行できない致命的なエラーに遭遇したことを示します。
36                // この定数を返すと、ストリーム操作は失敗し、エラーが報告されます。
37                error_log("MySimpleStreamFilter: 致命的なエラーを検出しました。'ERROR'が含まれています。");
38                return PSFS_ERR_FATAL; // 致命的なエラーが発生したため、フィルターを停止
39            }
40
41            // データを大文字に変換するシンプルな処理
42            $processedData = strtoupper($originalData);
43
44            $consumed += $bucket->datalen; // 処理されたバイト数を合計に追加
45            $bucket->data = $processedData; // 処理済みのデータをバケットに設定
46
47            // 処理済みのバケットを出力ストリームに追加
48            stream_bucket_append($out, $bucket);
49        }
50
51        // PSFS_PASS_ON は、データが正常に処理され、次のフィルターまたは最終的な宛先に渡されるべきであることを示します。
52        // エラーがなければ、この定数を返して処理を続行します。
53        return PSFS_PASS_ON;
54    }
55}
56
57// ----------------------------------------------------
58// ストリームフィルターの利用例
59// ----------------------------------------------------
60
61// 1. カスタムフィルターをシステムに登録します。
62// 'my.upper.filter' という名前で MySimpleStreamFilter クラスが使えるようになります。
63if (!stream_filter_register('my.upper.filter', MySimpleStreamFilter::class)) {
64    die("エラー: フィルター 'my.upper.filter' の登録に失敗しました。\n");
65}
66
67echo "フィルター 'my.upper.filter' が正常に登録されました。\n";
68
69// --- 成功するケース: PSFS_PASS_ON が返されるシナリオ ---
70echo "\n--- 成功ケースのテスト (データが正常に処理される) ---\n";
71// テンポラリストリームを開き、カスタムフィルターを書き込みモードに適用します。
72// 'php://temp' は、メモリまたは一時ファイルにデータを保持する仮想ストリームです。
73$handleSuccess = fopen('php://temp', 'r+');
74if ($handleSuccess) {
75    // ストリームにデータを書き込む際にフィルターを適用するよう設定
76    stream_filter_append($handleSuccess, 'my.upper.filter', STREAM_FILTER_WRITE);
77
78    fwrite($handleSuccess, "Hello World!\n");
79    fwrite($handleSuccess, "This is a test message.\n");
80
81    fseek($handleSuccess, 0); // ストリームの先頭に戻って、処理されたデータを読み込み準備
82
83    echo "フィルター適用後の読み込み結果:\n";
84    // フィルターは書き込み時にデータを処理するため、読み込み時には既に大文字に変換されています。
85    echo stream_get_contents($handleSuccess);
86    fclose($handleSuccess);
87    echo "成功ケースが完了しました。\n";
88} else {
89    echo "エラー: php://temp ストリームを開けませんでした (成功ケース)。\n";
90}
91
92// --- エラーケース: PSFS_ERR_FATAL が返されるシナリオ ---
93echo "\n--- エラーケースのテスト (フィルターで致命的なエラーが発生) ---\n";
94$handleError = fopen('php://temp', 'r+');
95if ($handleError) {
96    // ストリームにデータを書き込む際にフィルターを適用するよう設定
97    stream_filter_append($handleError, 'my.upper.filter', STREAM_FILTER_WRITE);
98
99    echo "エラーを引き起こす文字列を書き込み中...\n";
100    fwrite($handleError, "This data contains an ERROR string.\n"); // フィルターで「ERROR」を検出
101    fwrite($handleError, "Further data will not be processed.\n"); // このデータは処理されないはず
102
103    fseek($handleError, 0); // ストリームの先頭に戻る
104
105    echo "フィルター適用後の読み込み結果 (エラー発生後):\n";
106    // @ を付けて、stream_get_contents() がフィルターエラーで警告を出すのを抑制します。
107    // 致命的なエラーが発生すると、通常、それ以降のストリーム操作は失敗します。
108    // 結果として、データが読み取れなかったり、不完全なデータが返されたりします。
109    $content = @stream_get_contents($handleError);
110
111    if ($content === false || $content === '') {
112        echo "ストリームフィルターで致命的なエラーが発生したため、データが正常に読み取れませんでした。\n";
113        // PHPのエラーログには、MySimpleStreamFilterクラスで出力したエラーメッセージが記録されます。
114    } else {
115        echo $content; // エラーが発生した場合は、ここには何も表示されないか、不完全なデータが表示されることがあります。
116    }
117    fclose($handleError);
118    echo "エラーケースが完了しました。\n";
119} else {
120    echo "エラー: php://temp ストリームを開けませんでした (エラーケース)。\n";
121}
122

このPHPコードは、php_user_filterを継承したMySimpleStreamFilterクラスを使い、カスタムのストリームフィルターを定義しています。ストリームフィルターとは、ファイルやネットワーク接続など、データが流れる「ストリーム」の途中でデータを加工するためのPHPの機能です。

このフィルターの核となるのはfilterメソッドで、ここでは入力データ（$in）を処理し、変換したデータを出力（$out）に渡します。処理されたデータのバイト数は&$consumedに記録されます。

PSFS_PASS_ONは、フィルターが入力データを正常に処理し、次のフィルターまたは最終的な宛先にそのデータを渡して処理を継続すべきであることを示す定数です。コードでは、特別なエラーが検出されなかった場合にこの定数を返しています。

一方、PSFS_ERR_FATALは、フィルター処理中に回復不可能な致命的なエラーが発生し、それ以上データの処理を続行できない場合に返される定数です。この定数が返されると、ストリーム操作は失敗し、エラーとして扱われます。サンプルコードでは、入力データに「ERROR」という文字列が含まれていた場合に、致命的なエラーとしてPSFS_ERR_FATALを返しています。

コードの後半では、このカスタムフィルターをシステムに登録し、php://tempストリームに適用してその動作をテストしています。成功ケースではデータが大文字に変換され、PSFS_PASS_ONが返されて処理が正常に完了します。エラーケースでは「ERROR」を含む文字列を書き込むとPSFS_ERR_FATALが返され、それ以降のストリーム操作が中断される様子が示されています。

Copy
1<?php
2
3/**
4 * この関数は、特定のPHP拡張機能が提供する定数 PSFS_ERR_FATAL の利用例を示します。
5 * PSFS_ERR_FATAL は、架空の php_psr.dll 拡張機能の一部として提供される、
6 * ファイルシステム関連の致命的なエラーを示す定数であると仮定しています。
7 *
8 * システムエンジニアを目指す初心者の方へ：
9 * 定数は、プログラム実行中に変わることのない固定の値を保持します。
10 * 拡張機能が提供する定数は、その拡張機能がPHPにロードされている場合にのみ利用可能です。
11 * 未定義の定数にアクセスしようとするとエラーになるため、使用前に存在を確認することが重要です。
12 */
13function demonstratePsfsErrorConstantUsage(): void
14{
15    echo "PSFS_ERR_FATAL 定数の利用状況を確認します。" . PHP_EOL;
16
17    // `defined()` 関数を使って、定数 'PSFS_ERR_FATAL' が定義されているか確認します。
18    // もし関連する 'php_psr.dll' 拡張機能がロードされていなければ、この定数は通常定義されません。
19    if (defined('PSFS_ERR_FATAL')) {
20        // 定数が定義されている場合、その値を出力します。
21        // この値は、プログラム内で特定のエラー状態を識別するために使用されます。
22        echo "定数 'PSFS_ERR_FATAL' は定義されています。その値: " . PSFS_ERR_FATAL . PHP_EOL;
23        echo "通常、この定数の値を使用して、特定の致命的なエラー状況に対応するロジックを実装します。" . PHP_EOL;
24    } else {
25        // 定数が定義されていない場合、その旨をユーザーに伝えます。
26        echo "定数 'PSFS_ERR_FATAL' は定義されていません。" . PHP_EOL;
27        echo "これは、この定数を提供する 'php_psr.dll' (または同等の) 拡張機能が" . PHP_EOL;
28        echo "PHP 環境にインストールされ、有効になっていない可能性を示唆しています。" . PHP_EOL;
29        echo "もしこの定数が必要な場合は、関連する拡張機能が正しく設定されているか確認してください。" . PHP_EOL;
30    }
31}
32
33// 関数を実行して、定数の状態を確認します。
34demonstratePsfsErrorConstantUsage();

このPHPのサンプルコードは、特定の拡張機能（ここでは架空のphp_psr.dllを想定）が提供する定数PSFS_ERR_FATALの利用方法を示しています。定数とは、プログラムの実行中に値が変わることのない固定された値を持つ識別子です。PSFS_ERR_FATALは、ファイルシステム関連の致命的なエラーを示すために使われる数値や文字列などの値を持つと仮定しています。

コード中のdemonstratePsfsErrorConstantUsage関数は、引数を一切取らず（引数なし）、特定の値も返しません（戻り値なし）。この関数内で、まずdefined()関数を使ってPSFS_ERR_FATALが現在のPHP環境で定義されているかを確認します。もしこの定数が定義されていれば、その値を出力し、エラー処理のロジックに利用できることを説明します。一方、定義されていない場合は、その定数を提供する拡張機能がPHPにロードされていない可能性が高いことを示唆します。拡張機能の定数は、その拡張機能が有効な場合にのみ利用できるため、使用前には必ずdefined()関数などで存在を確認することが、予期せぬエラーを防ぐ上で非常に重要です。