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

Copy
1<?php
2
3/**
4 * カスタムストリームフィルターの基底クラス。
5 * php_user_filter を継承することで、独自のデータ処理ロジックをストリームに適用できます。
6 *
7 * この例では、特に onCreate メソッドが「一度だけ」実行される特性に焦点を当てています。
8 */
9class MyOnceFilter extends php_user_filter
10{
11    /**
12     * フィルターが初めてインスタンス化され、ストリームにアタッチされる際に一度だけ呼び出される初期化メソッド。
13     *
14     * このメソッドは、フィルターのライフサイクルで一度だけ実行されることが保証されるため、
15     * 「php once」というキーワードに最も関連性の高い機能と言えます。
16     * ここで、フィルター固有の初期設定やリソースの確保などを行います。
17     *
18     * @return bool フィルターの初期化が成功した場合は true、失敗した場合は false を返します。
19     *              false を返すと、フィルターのアタッチに失敗し、E_WARNING が発生します。
20     */
21    public function onCreate(): bool
22    {
23        // ここに、フィルターリソースが「一度だけ」実行される初期化処理を記述します。
24        // 例えば、特定のログファイルの初期化、設定データの読み込み、
25        // フィルターインスタンス全体で共有するリソースの準備など、
26        // フィルターが初めて使われる際に一度だけ行いたい処理に最適です。
27        echo "--- MyOnceFilter::onCreate() が一度だけ呼び出されました。---\n";
28
29        // 必要に応じて、フィルターインスタンスのプロパティを初期化できます。
30        // 例: $this->params['initialized_timestamp'] = time();
31
32        return true; // 初期化が成功したことを示す
33    }
34
35    /**
36     * ストリームデータがフィルターを通過する際に繰り返し呼び出されるメソッド。
37     *
38     * この例では、onCreate メソッドの動作を示すことが主な目的であるため、
39     * データをそのまま通過させるだけのシンプルな実装にとどめます。
40     * 実際のフィルターでは、ここでデータの変換や加工などの処理を行います。
41     *
42     * @param resource $in 入力バケットブリゲード。フィルタリング対象のデータが含まれます。
43     * @param resource $out 出力バケットブリゲード。フィルタリング結果のデータをここに追加します。
44     * @param int $consumed 消費されたデータ量。参照渡しで、処理したバイト数を加算します。
45     * @param bool $closing ストリームが閉じられようとしているかを示すフラグ。
46     * @return int フィルター処理の結果を示す定数を返します (例: PSFS_PASS_ON, PSFS_FEED_ME, PSFS_ERR_FATAL)。
47     */
48    public function filter($in, $out, &$consumed, $closing): int
49    {
50        while ($bucket = stream_bucket_make_writeable($in)) {
51            // 入力バケットからデータを読み取り、そのまま出力バケットに追加
52            $consumed += $bucket->datalen;
53            stream_bucket_append($out, $bucket);
54        }
55        return PSFS_PASS_ON; // データをそのまま次のフィルターまたはストリームに渡す
56    }
57
58    /**
59     * フィルターが閉じられる際に一度だけ呼び出されるメソッド。
60     *
61     * onCreate で確保したリソースの解放や、最終処理などが必要な場合に利用します。
62     */
63    public function onClose(): void
64    {
65        echo "--- MyOnceFilter::onClose() が呼び出されました。---\n";
66    }
67}
68
69// -----------------------------------------------------------
70// フィルターの利用例
71// -----------------------------------------------------------
72
73// 1. カスタムフィルターをシステムに登録します。
74// この登録自体は複数回実行されても問題ありません。
75// 実際にフィルターがインスタンス化され、onCreate() が呼び出されるのは、
76// そのフィルターがストリームにアタッチされた時です。
77stream_filter_register("my_once_filter", MyOnceFilter::class);
78echo "カスタムフィルター 'my_once_filter' が登録されました。\n\n";
79
80// 2. 一時的なファイルストリームを作成します。
81// php://temp はメモリまたは一時ファイルにデータを保持するストリームです。
82$fp = fopen("php://temp", "r+");
83
84if ($fp) {
85    echo "ストリームにフィルターをアタッチします...\n";
86    // 3. ストリームにカスタムフィルターをアタッチします。
87    // ここで MyOnceFilter クラスのインスタンスが作成され、
88    // その際に onCreate() メソッドが「一度だけ」呼び出されます。
89    stream_filter_append($fp, "my_once_filter");
90    echo "フィルターがストリームにアタッチされました。\n\n";
91
92    echo "ストリームにデータを書き込みます...\n";
93    fwrite($fp, "Hello from Filtered Stream!\n");
94    fwrite($fp, "This is the second line.\n");
95    echo "データの書き込みが完了しました。\n\n";
96
97    // ポインタを先頭に戻して、フィルターを通ったデータを読み込みます。
98    fseek($fp, 0);
99    echo "ストリームからデータを読み込みます:\n";
100    echo stream_get_contents($fp);
101    echo "データの読み込みが完了しました。\n\n";
102
103    // 4. ストリームを閉じます。
104    // ストリームが閉じられる際に onClose() メソッドが呼び出されます。
105    fclose($fp);
106    echo "ストリームが閉じられました。\n";
107} else {
108    echo "一時ファイルストリームを開けませんでした。\n";
109}
110
111?>

php_user_filter::onCreateは、PHPのカスタムストリームフィルターにおいて、フィルターがストリームに初めてアタッチされる際に一度だけ呼び出される初期化メソッドです。このメソッドは、フィルターのライフサイクルで一度だけ実行されることが保証されるため、「php once」というキーワードに深く関連する機能を提供します。

このメソッドは引数を取りません。戻り値はbool型で、フィルターの初期化が成功した場合はtrue、失敗した場合はfalseを返します。falseを返すとフィルターのアタッチが失敗し、警告（E_WARNING）が発生します。

onCreateメソッドは、フィルター全体で共有するリソースの確保、特定のログファイルの初期化、設定データの読み込みなど、ストリーム処理を開始する前に一度だけ行いたい準備処理に最適です。

サンプルコードでは、MyOnceFilterクラスがphp_user_filterを継承し、onCreateメソッド内で「一度だけ呼び出されました」というメッセージを出力しています。フィルターを登録後、stream_filter_append関数を使って一時的なストリームにフィルターをアタッチすると、このonCreateメソッドが実行される様子が確認できます。これは、フィルターの初期設定が確実に一度だけ行われることを示しており、ストリームフィルターがデータ処理の前に必要な準備を効率的に行うことができる仕組みです。

Copy
1<?php
2
3/**
4 * カスタムストリームフィルターの例。
5 * php_user_filterを継承し、onCreateメソッドを実装することで
6 * フィルターがインスタンス化される際の初期化処理を定義します。
7 *
8 * このフィルターは、データに特別な変換は行わず、
9 * 主にonCreateメソッドの動作を示すために使用されます。
10 */
11class MyCustomFilter extends php_user_filter
12{
13    /**
14     * このフィルターのインスタンスが作成されたときに一度だけ呼び出されます。
15     * ストリームリソースがオープンされ、このフィルターがストリームに付加される直前に実行されます。
16     * ここでフィルター固有の初期化処理（例えば、設定値の読み込みや内部リソースの準備など）を行います。
17     *
18     * @return bool フィルターの初期化が成功した場合は true、失敗した場合は false を返します。
19     *              false を返すと、フィルターの登録または付加に失敗し、警告が発生します。
20     */
21    public function onCreate(): bool
22    {
23        // フィルターが初期化されたことを示すメッセージをログに出力します。
24        // このメッセージは、スクリプト実行時に一度だけ表示されます。
25        error_log("MyCustomFilter::onCreate() が呼び出されました。フィルターが正常に初期化されます。");
26
27        // 初期化が成功したと見なして true を返します。
28        return true;
29    }
30
31    /**
32     * ストリームにデータが読み書きされる際に呼び出されるメソッドです。
33     * onCreateとは異なり、データがある限り複数回呼び出されます。
34     * 今回はonCreateの動作確認が目的なので、フィルタリングは行わず、データをそのまま通過させます。
35     *
36     * @param resource $in     入力バケットブリッジ
37     * @param resource $out    出力バケットブリッジ
38     * @param int      &$consumed 消費されたデータのバイト数
39     * @param bool     $closing  ストリームが閉じられているかどうか
40     * @return int フィルター処理の結果を示す定数 (PSFS_PASS_ON, PSFS_FEED_ME, PSFS_ERR_FATAL)
41     */
42    public function filter($in, $out, &$consumed, bool $closing): int
43    {
44        // 入力からバケットを取得し、出力にそのまま渡します。
45        while ($bucket = stream_bucket_make_writeable($in)) {
46            // ここにデータ変換ロジックを記述できますが、今回は何もしません。
47            stream_bucket_append($out, $bucket);
48            $consumed += $bucket->datalen; // 消費したデータ量を更新
49        }
50        return PSFS_PASS_ON; // データをそのまま通過させることを示します
51    }
52}
53
54// -------------------------------------------------------------------------
55// 以下は、上記で定義したカスタムフィルターの使用例です。
56// このコードを実行することで、onCreateメソッドが呼び出されることを確認できます。
57// -------------------------------------------------------------------------
58
59// カスタムフィルターを "my_simple_filter" という名前でPHPのストリームフィルターシステムに登録します。
60if (!stream_filter_register("my_simple_filter", MyCustomFilter::class)) {
61    echo "エラー: カスタムフィルター 'my_simple_filter' の登録に失敗しました。\n";
62    exit(1);
63}
64
65echo "カスタムフィルター 'my_simple_filter' が正常に登録されました。\n";
66
67// 一時的なメモリストリーム（ファイルのように扱える）を開きます。
68$fp = fopen("php://temp", "r+");
69if ($fp === false) {
70    echo "エラー: ストリームのオープンに失敗しました。\n";
71    exit(1);
72}
73
74echo "ストリームをオープンしました。\n";
75
76// オープンしたストリームに、登録したカスタムフィルターを付加します。
77// この `stream_filter_append()` の呼び出しにより、
78// MyCustomFilter クラスの `onCreate()` メソッドが一度だけ呼び出されます。
79if (stream_filter_append($fp, "my_simple_filter", STREAM_FILTER_WRITE) === false) {
80    echo "エラー: フィルター 'my_simple_filter' の付加に失敗しました。\n";
81    fclose($fp);
82    exit(1);
83}
84
85echo "カスタムフィルター 'my_simple_filter' をストリームに付加しました。\n";
86echo "↑↑↑ MyCustomFilter::onCreate() メソッドがこの時点で呼び出されるはずです。\n";
87echo "   (メッセージはWebサーバーのログやCLIのstderrに出力されます)\n\n";
88
89
90// ストリームにデータを書き込みます。
91// この書き込み操作中に MyCustomFilter::filter() メソッドが呼び出されますが、
92// onCreate() は呼び出されません（既に初期化済みのため）。
93$data = "Hello, PHP Stream Filter onCreate Example!\n";
94$bytesWritten = fwrite($fp, $data);
95if ($bytesWritten === false) {
96    echo "エラー: ストリームへのデータ書き込みに失敗しました。\n";
97} else {
98    echo "ストリームに {$bytesWritten} バイトのデータを書き込みました。\n";
99}
100
101// ストリームポインタを先頭に戻し、書き込んだ内容を読み取ります。
102rewind($fp);
103echo "\nストリームから読み取った内容:\n";
104echo stream_get_contents($fp);
105
106// ストリームを閉じ、使用したリソースを解放します。
107fclose($fp);
108echo "\nストリームを閉じました。\n";
109
110// プログラムを実行し、標準エラー出力 (またはPHP設定されたログファイル) を確認すると、
111// MyCustomFilter::onCreate() からのメッセージが表示されているはずです。
112?>

php_user_filter::onCreateメソッドは、PHPでカスタムストリームフィルターを定義する際に利用される、非常に重要な初期化メソッドです。このメソッドは、php_user_filterクラスを継承して作成される独自のフィルタークラスに実装されます。

主な役割は、フィルターのインスタンスが作成され、ストリーム（ファイルやネットワーク接続など）に付加される直前に、必要な初期化処理を一度だけ行うことです。例えば、フィルター固有の設定値を読み込んだり、内部で使用するリソースを準備したりする処理を記述します。

このonCreateメソッドは引数を一切取りません。戻り値はbool型で、フィルターの初期化が成功した場合はtrueを、何らかの理由で失敗した場合はfalseを返します。もしfalseを返した場合、フィルターの登録やストリームへの付加が失敗したとみなされ、PHPから警告が出力されることになります。

サンプルコードでは、MyCustomFilterクラス内でonCreateメソッドが実装されており、フィルターが初期化された際にログにメッセージを出力しています。これは、stream_filter_append()関数が呼び出されてフィルターがストリームに適用される瞬間に一度だけ実行され、その初期化処理が正しく動作することを確認するための例です。