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

Copy
1<?php
2
3/**
4 * カスタムストリームフィルタクラス。
5 * PHPのストリーム操作中にデータに介入するために `php_user_filter` を継承します。
6 * `onClose` メソッドの動作をデモンストレーションすることを目的としています。
7 */
8class MyLogFilter extends php_user_filter
9{
10    /** @var string フィルタの処理状況を記録する一時ログファイルのパス。 */
11    private string $logFilePath;
12
13    /** @var string|null 最後に生成されたログファイルのパスを保持する静的プロパティ。 */
14    public static ?string $lastLogFile = null;
15
16    /**
17     * フィルタインスタンスが作成されるときに呼び出されます。
18     * ログファイルの設定など、初期化処理を行います。
19     *
20     * @return bool フィルタの作成が成功した場合 true、失敗した場合 false。
21     */
22    public function onCreate(): bool
23    {
24        // ユニークな一時ログファイル名を生成し、ログファイルのパスを設定します。
25        $this->logFilePath = sys_get_temp_dir() . '/onclose_demo_log_' . uniqid() . '.txt';
26        file_put_contents($this->logFilePath, "[Filter Created] Log file initialized: " . $this->logFilePath . "\n", FILE_APPEND);
27        return true;
28    }
29
30    /**
31     * ストリームデータがフィルタを通過する際に呼び出されます。
32     * ここでデータの読み書きに介入し、内容をログに記録します。
33     *
34     * @param resource $in  入力バケットブリゲード（読み込まれたデータ源）
35     * @param resource $out 出力バケットブリゲード（データ送り先）
36     * @param int      &$consumed 消費されたデータのバイト数
37     * @param bool     $closing ストリームが閉じられようとしているかどうかのフラグ
38     * @return int フィルタリングのステータス (例: PSFS_PASS_ON でデータをそのまま通過)
39     */
40    public function filter($in, $out, &$consumed, bool $closing): int
41    {
42        while ($bucket = stream_bucket_make_writeable($in)) {
43            // ストリームを通過するデータの最初の数バイトをログに記録します。
44            $logMessage = "[Filter Data] Processed " . $bucket->datalen . " bytes. Sample: '" . substr($bucket->data, 0, 20) . "'...\n";
45            file_put_contents($this->logFilePath, $logMessage, FILE_APPEND);
46
47            $consumed += $bucket->datalen;
48            stream_bucket_append($out, $bucket); // データを次のフィルタまたは最終目的地へ渡します。
49        }
50        return PSFS_PASS_ON; // データをそのまま通過させることを示します。
51    }
52
53    /**
54     * ストリームが閉じられる際に自動的に呼び出されます。
55     * このメソッドは引数を受け取らず、戻り値もありません。
56     * リソースの解放や最終的なログ記録など、ストリーム終了時のクリーンアップ処理を行います。
57     * このサンプルコードの主な焦点となるメソッドです。
58     */
59    public function onClose(): void
60    {
61        // ストリームが閉じられたことをログに記録します。
62        file_put_contents($this->logFilePath, "[Filter Closed] Stream operation completed and closed.\n", FILE_APPEND);
63
64        // 生成されたログファイルのパスを静的プロパティに保存し、
65        // PHPスクリプトのメイン部分で参照できるようにします。
66        self::$lastLogFile = $this->logFilePath;
67    }
68}
69
70// 作成したカスタムフィルタをPHPランタイムに登録します。
71// これにより、'my.log.filter' という名前でストリームフィルタを利用できるようになります。
72stream_filter_register('my.log.filter', MyLogFilter::class)
73    or die("Failed to register stream filter 'my.log.filter'");
74
75// === 以下は、Webページとして動作し、フィルタ操作をトリガーするコードです ===
76
77// HTTP POSTリクエストがあり、アクションが 'trigger_filter' の場合、フィルタ操作を実行します。
78if ($_SERVER['REQUEST_METHOD'] === 'POST' && isset($_POST['action']) && $_POST['action'] === 'trigger_filter') {
79    echo '<h2>フィルタ操作結果:</h2>';
80
81    // 一時的なストリーム（メモリまたはディスク）を開きます。
82    // このストリームにフィルタを適用して、`onClose()` の呼び出しをデモンストレーションします。
83    $fp = fopen('php://temp', 'r+');
84
85    // 開いたストリームにカスタムフィルタを書き込みモードで追加します。
86    // これにより、`fwrite()` で書き込まれるデータが `MyLogFilter::filter()` を通過します。
87    stream_filter_append($fp, 'my.log.filter', STREAM_FILTER_WRITE);
88
89    $dataToWrite = "This is some sample data for the stream filter demonstration.\n"
90                 . "The onClose method will be called when this stream is closed.\n"
91                 . "Final line of data.";
92
93    // ストリームにデータを書き込みます。この際 `filter()` メソッドが呼び出されます。
94    fwrite($fp, $dataToWrite);
95
96    // ストリームを閉じます。この操作の完了時に `MyLogFilter::onClose()` メソッドが自動的に呼び出されます。
97    fclose($fp);
98
99    echo '<p>ストリーム操作が完了しました。<code>MyLogFilter::onClose()</code> メソッドが実行されました。</p>';
100
101    // `onClose()` で静的プロパティに保存されたログファイルパスがあれば、その内容を表示するリンクを生成します。
102    if (MyLogFilter::$lastLogFile && file_exists(MyLogFilter::$lastLogFile)) {
103        $logContent = file_get_contents(MyLogFilter::$lastLogFile);
104        // JavaScriptのalert()で表示するためにログ内容を適切にエスケープします。
105        $escapedLogContent = htmlspecialchars(str_replace(["\n", "'"], ["\\n", "\\'"], $logContent), ENT_QUOTES, 'UTF-8');
106        echo '<p>詳細ログ: <a href="#" onclick="alert(\'' . $escapedLogContent . '\'); return false;">ログ内容を表示</a></p>';
107        unlink(MyLogFilter::$lastLogFile); // ログファイルは表示後に削除してクリーンアップします。
108        MyLogFilter::$lastLogFile = null;  // 静的プロパティをリセットします。
109    } else {
110        echo '<p>ログファイルが見つかりませんでした。</p>';
111    }
112
113    echo '<p><a href="/">もう一度試す</a></p>';
114
115} else {
116    // 最初のページアクセスまたはGETリクエストの場合に、フィルタ操作をトリガーするHTMLフォームを表示します。
117    ?>
118    <!DOCTYPE html>
119    <html lang="ja">
120    <head>
121        <meta charset="UTF-8">
122        <meta name="viewport" content="width=device-width, initial-scale=1.0">
123        <title>PHP php_user_filter::onClose デモ</title>
124        <style>
125            body { font-family: sans-serif; margin: 20px; background-color: #f0f2f5; color: #333; }
126            .container { max-width: 700px; margin: 30px auto; padding: 30px; background-color: #fff; border-radius: 8px; box-shadow: 0 4px 10px rgba(0,0,0,0.1); }
127            h1 { color: #007bff; text-align: center; margin-bottom: 25px; }
128            p { line-height: 1.6; margin-bottom: 15px; }
129            code { background-color: #e9ecef; padding: 2px 4px; border-radius: 3px; font-family: monospace; }
130            button { background-color: #28a745; color: white; border: none; padding: 12px 25px; border-radius: 5px; font-size: 1em; cursor: pointer; transition: background-color 0.3s ease; display: block; margin: 25px auto; }
131            button:hover { background-color: #218838; }
132            button:disabled { background-color: #cccccc; cursor: not-allowed; }
133            a { color: #007bff; text-decoration: none; }
134            a:hover { text-decoration: underline; }
135        </style>
136    </head>
137    <body>
138        <div class="container">
139            <h1><code>php_user_filter::onClose</code> のデモンストレーション</h1>
140            <p>
141                このデモでは、<code>php_user_filter</code> を継承して作成されたカスタムフィルタの <code>onClose()</code> メソッドの動作を示します。<br>
142                以下のボタンを<b>クリック</b>すると、PHPサーバーでストリーム操作が実行され、そのストリームが閉じられる際に <code>onClose()</code> が呼び出されます。
143            </p>
144            <p><code>onClose()</code> メソッドは、ストリーム処理の終了時に必要なクリーンアップや最終処理を行うために使用されます。</p>
145
146            <form method="post" action="">
147                <input type="hidden" name="action" value="trigger_filter">
148                <button type="submit" onclick="this.disabled=true; this.innerText='処理中...'; this.form.submit();">
149                    フィルタ操作をトリガー
150                </button>
151            </form>
152        </div>
153    </body>
154    </html>
155    <?php
156}
157?>

このサンプルコードは、PHP 8でカスタムストリームフィルタを作成するための php_user_filter クラスと、その onClose メソッドの動作をデモンストレーションするものです。

php_user_filter は、ファイルやネットワーク接続といったストリームに対するデータの読み書き処理に介入し、内容を加工したり監視したりするためのクラスです。MyLogFilter クラスはこれを継承し、ストリーム操作の各段階で処理を行います。

特に onClose() メソッドは、引数を一切取らず、戻り値もありませんが、ストリームが fclose() などによって閉じられた際に、PHPランタイムによって自動的に呼び出されます。このメソッドは、ストリーム処理の完了時に発生する最後のイベントであり、使用されたリソースの解放や、最終的なログ記録、クリーンアップといった後処理を実行するのに適しています。

サンプルコードでは、ウェブページに表示されたボタンを onclick イベントでクリックすると、PHPサーバーで一時的なストリームが開かれ、MyLogFilter が適用されます。データがストリームに書き込まれた後、ストリームが閉じられると、MyLogFilter::onClose() が実行され、その動作ログが生成されます。これにより、onClose() メソッドがストリームの終了処理においてどのように機能するかを具体的に確認できます。

Copy
1<?php
2
3/**
4 * カスタムストリームフィルターの例。
5 * このフィルターは、ストリームが閉じられる際に特定のクリーンアップ処理を行います。
6 *
7 * システムエンジニアを目指す初心者の方へ:
8 * PHPはサーバーサイドで動作し、ウェブページを生成することがよくあります。
9 * このコードはサーバーサイドのストリーム処理の一部ですが、
10 * 最終的にブラウザに送られるHTMLコンテンツ（JavaScriptの `onclick` イベントや `return` 文を含む可能性もあります）
11 * を生成する一連の処理の一部となることがあります。
12 */
13class MyCleanupFilter extends php_user_filter
14{
15    /**
16     * このフィルター内で収集されたログメッセージを保持する配列。
17     * onCloseメソッドでまとめて処理されます。
18     *
19     * @var string[]
20     */
21    private array $collectedLogs = [];
22
23    /**
24     * ストリームデータがフィルタリングされる際に呼び出されます。
25     * この例では、データをそのまま通過させつつ、処理のログを収集します。
26     *
27     * @param resource $in 入力バケットブリゲード (読み込むデータ)
28     * @param resource $out 出力バケットブリゲード (書き出すデータ)
29     * @param int $consumed 消費されたデータ量 (参照渡し)
30     * @param bool $closing ストリームが閉じられようとしているか
31     * @return int 成功時は PSFS_PASS_ON、失敗時は PSFS_ERR_FATAL
32     */
33    public function filter($in, $out, &$consumed, $closing): int
34    {
35        while ($bucket = stream_bucket_make_writeable($in)) {
36            // ここでデータのフィルタリング処理を行うことができます。
37            // この例では、データを変更せずにそのまま出力に渡します。
38            stream_bucket_append($out, $bucket);
39            $consumed += $bucket->datalen;
40
41            // データのチャンクを処理したことをログに記録します。
42            $this->collectedLogs[] = 'Processed data chunk (' . $bucket->datalen . ' bytes)';
43        }
44        return PSFS_PASS_ON;
45    }
46
47    /**
48     * ストリームフィルターが閉じられるときに呼び出されます。
49     * 引数はありません。戻り値もありません (void)。
50     *
51     * このメソッドは、フィルターに関連するリソースの解放や、
52     * 収集した情報の最終的な保存（例: ログファイルへの書き込み、データベースへの保存）など、
53     * クリーンアップ処理を行うのに最適な場所です。
54     *
55     * キーワード「php onclick return」は、クライアントサイドのJavaScriptに関連しますが、
56     * この `onClose` メソッドはサーバーサイドでストリーム処理が完結する際に実行されます。
57     * 例えば、このストリームフィルターが特定のファイル操作を行っていて、
58     * その操作の完了をログに記録し、そのログが後でWeb管理画面で `onclick` イベントを通じて
59     * 表示・操作される、といったシナリオの一部として機能することが考えられます。
60     */
61    public function onClose(): void
62    {
63        // フィルターが閉じられた際のクリーンアップ処理を記述します。
64        // 例として、これまでに収集したログメッセージをエラーログに出力します。
65        error_log("--- MyCleanupFilter::onClose() が呼び出されました ---");
66        error_log("フィルター処理中に収集されたログ:");
67        foreach ($this->collectedLogs as $index => $logMessage) {
68            error_log("  [" . ($index + 1) . "] " . $logMessage);
69        }
70        error_log("--- クリーンアップ処理完了 ---");
71
72        // 実際のアプリケーションでは、ここでファイルハンドルを閉じたり、
73        // データベース接続を解放したりするなどの処理が行われます。
74        // 例: $this->someResource->close();
75    }
76}
77
78// -----------------------------------------------------------
79// 以下は、MyCleanupFilter クラスの単体動作デモンストレーションです。
80// -----------------------------------------------------------
81
82// 1. カスタムフィルターを登録します。
83if (stream_filter_register("my_cleanup_filter", MyCleanupFilter::class)) {
84    echo "フィルター 'my_cleanup_filter' が登録されました。\n\n";
85
86    // 2. フィルタリングされるダミーファイルを作成します。
87    $dummyFilePath = 'test_data.txt';
88    file_put_contents($dummyFilePath, "Hello, world!\n");
89    file_put_contents($dummyFilePath, "This is a test line.\n", FILE_APPEND);
90    file_put_contents($dummyFilePath, "End of file content.\n", FILE_APPEND);
91    echo "ダミーファイル '{$dummyFilePath}' にテストデータを書き込みました。\n";
92
93    // 3. ストリームを開き、登録したフィルターをアタッチしてデータを読み込みます。
94    // 'r' (読み込み) モードでストリームを開くことで、読み込み時にフィルターが適用されます。
95    $filteredStream = fopen("php://filter/read=my_cleanup_filter/resource={$dummyFilePath}", "r");
96
97    if ($filteredStream) {
98        echo "フィルター付きストリームを開きました。データ読み込み中...\n";
99        echo "--- フィルタリングされたデータの内容 ---\n";
100        while (!feof($filteredStream)) {
101            // fgets() を呼び出すたびに、MyCleanupFilter::filter() メソッドが内部的に呼び出されます。
102            echo fgets($filteredStream);
103        }
104        echo "--- データ読み込み完了 ---\n";
105
106        // 4. ストリームを閉じると、MyCleanupFilter::onClose() メソッドが自動的に呼び出されます。
107        fclose($filteredStream);
108        echo "\nストリームを閉じました。MyCleanupFilter::onClose() メソッドが呼び出されたはずです。\n";
109        echo "onClose() メソッドからの出力は、サーバーのエラーログ（またはコンソール）を確認してください。\n";
110    } else {
111        echo "エラー: フィルター付きストリームを開けませんでした。\n";
112    }
113
114    // 5. 使用したダミーファイルをクリーンアップします。
115    if (file_exists($dummyFilePath)) {
116        unlink($dummyFilePath);
117        echo "ダミーファイル '{$dummyFilePath}' を削除しました。\n";
118    }
119
120} else {
121    echo "エラー: フィルター 'my_cleanup_filter' の登録に失敗しました。\n";
122}
123
124?>

PHPのphp_user_filterクラスに属するonCloseメソッドは、カスタムストリームフィルターが閉じられる際に自動的に呼び出される特別なメソッドです。このメソッドは引数を持たず、いかなる値も返しません（void）。

その主な役割は、ストリーム処理の完了時に必要なクリーンアップ作業を行うことです。例えば、フィルター内で開いていたファイルハンドルを閉じたり、データベース接続を解放したり、あるいは処理中に収集したデータを最終的な保存先に書き出す（ログファイルへの出力やデータベースへの記録など）といった用途で利用されます。これにより、リソースの適切な管理とデータの整合性確保が図られます。

システムエンジニアを目指す初心者の方へ。このonCloseメソッドは、PHPが動作するサーバーサイドで実行される処理です。ご質問のキーワードにあるonclickやreturnは、主にウェブブラウザ上で動くJavaScriptの機能に関連しますが、onCloseでサーバーサイドで生成された情報（例えば処理ログや結果データ）が、後からウェブページ上でJavaScriptのonclickイベントを通じて表示されたり操作されたりする、といった連携の可能性はあります。サーバー側の終了処理を確実に実行するための重要な仕組みです。