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

Copy
1<?php
2
3/**
4 * カスタム出力ハンドラ関数
5 *
6 * PHPの出力バッファリングシステムによって、出力がバッファに格納された際に呼び出されます。
7 * $buffer には現在バッファされている文字列が、$status にはハンドラが呼び出されたときの状態を示す
8 * ビットフラグ（PHP_OUTPUT_HANDLER_* 定数の組み合わせ）が渡されます。
9 *
10 * @param string $buffer 現在の出力バッファの内容
11 * @param int $status 出力ハンドラの状態を示すビットフラグ
12 * @return string 処理されたバッファの内容（この内容が出力されるか、次のハンドラに渡されます）
13 */
14function myOutputHandler(string $buffer, int $status): string
15{
16    // PHP_OUTPUT_HANDLER_STARTED は、出力処理が既に開始され、
17    // バッファにデータがある状態でハンドラが呼び出されたことを示します。
18    // このフラグは、通常、PHP_OUTPUT_HANDLER_CONT や PHP_OUTPUT_HANDLER_FINAL と組み合わせて使用されます。
19
20    $status_flags = [];
21    if ($status & PHP_OUTPUT_HANDLER_STARTED) {
22        $status_flags[] = 'STARTED';
23    }
24    if ($status & PHP_OUTPUT_HANDLER_CONT) {
25        $status_flags[] = 'CONTINUING';
26    }
27    if ($status & PHP_OUTPUT_HANDLER_FINAL) {
28        $status_flags[] = 'FINAL';
29    }
30
31    $status_str = implode(' | ', $status_flags);
32
33    // ハンドラが呼ばれたときのバッファの内容と状態を表示
34    // このメッセージは、最終的な出力の一部として表示されます。
35    $output = "--- Output Handler Called (Status: $status_str) ---\n";
36    $output .= "  Original Buffer: \"{$buffer}\"\n";
37    $output .= "  Processed Buffer: \"". strtoupper($buffer) . "\"\n"; // バッファの内容を大文字に変換
38    $output .= "---------------------------------------------------\n";
39
40    // 処理されたバッファの内容を返す
41    // 今回は、元のバッファを大文字に変換し、状態メッセージを付加しています。
42    return $output . strtoupper($buffer);
43}
44
45// 出力バッファリングを開始し、上記のカスタムハンドラ関数を登録します。
46// ob_start() が実行された時点では、ハンドラはまだ呼び出されません。
47ob_start('myOutputHandler');
48
49echo "Hello, ";
50echo "PHP output buffering ";
51echo "example!\n";
52
53// ob_end_flush() を呼び出すと、バッファリングを終了し、
54// バッファに溜まっていた内容がカスタムハンドラに渡され、
55// その戻り値が最終的にブラウザ（または標準出力）に出力されます。
56// このとき、ハンドラが呼び出され、$status 引数には PHP_OUTPUT_HANDLER_STARTED が含まれます。
57ob_end_flush();
58
59?>

PHP_OUTPUT_HANDLER_STARTEDは、PHPの出力バッファリングシステムにおいて、カスタム出力ハンドラ関数が呼び出された際の「状態」を示す定数の一つです。この定数は、出力処理が既に開始され、バッファにデータが存在する状態でハンドラが呼び出されたことを示します。

サンプルコードでは、myOutputHandlerというカスタム関数を定義し、ob_start()関数で出力バッファの開始と同時にこのハンドラを登録しています。myOutputHandler関数は、引数$bufferで現在の出力バッファの内容を受け取り、引数$statusでハンドラが呼び出されたときの状態を示すビットフラグを受け取ります。この関数は、受け取った$bufferの内容を加工し、その結果を文字列として戻り値で返します。この戻り値が最終的な出力となるか、次の出力ハンドラに渡されます。

echo文で出力された内容は直接画面に表示されず、内部バッファに一時的に格納されます。その後、ob_end_flush()関数が実行されると、バッファに溜まっていた内容がmyOutputHandler関数に渡され、その際に$status引数にはPHP_OUTPUT_HANDLER_STARTEDフラグが含まれています。これにより、開発者は出力ハンドラがどの処理段階で呼び出されたかを判断し、それに応じた適切な処理を実装することが可能となります。

Copy
1<?php
2
3/**
4 * このスクリプトは、PHPの出力バッファリングと
5 * PHP_OUTPUT_HANDLER_STARTED 定数の使い方を示します。
6 *
7 * システムエンジニアを目指す初心者向けに、出力バッファリングの基本的な仕組みと、
8 * 出力ハンドラコールバック関数内で現在のバッファリング状態を判断する方法を解説します。
9 */
10
11/**
12 * カスタム出力ハンドラ関数
13 *
14 * ob_start() 関数に渡されるコールバック関数です。
15 * 出力バッファに収集された内容がこの関数に渡され、加工して返されます。
16 *
17 * @param string $buffer 現在の出力バッファの内容
18 * @param int $flags 出力ハンドラへのフラグ（現在の状態を示す）
19 * @return string 加工された出力バッファの内容
20 */
21function myOutputHandler(string $buffer, int $flags): string
22{
23    // PHP_OUTPUT_HANDLER_STARTED は、出力バッファリングが開始された状態を示す定数です。
24    // コールバック関数が最初に呼び出された際などに、このフラグがセットされることがあります。
25    // ビット演算子 '&' を使用して、特定のフラグがセットされているかチェックします。
26    if ($flags & PHP_OUTPUT_HANDLER_STARTED) {
27        // 出力バッファリングが「開始された」状態、または初回処理中の場合
28        echo "\n<!-- 出力バッファリングが開始された状態です (PHP_OUTPUT_HANDLER_STARTED フラグ検出) -->\n";
29        // バッファの内容を大文字に変換し、識別子を追加して返します。
30        return "--- START ---\n" . strtoupper($buffer) . "\n";
31    } else {
32        // その他の状態（例: ob_end_flush()などでバッファがフラッシュされる最終段階）
33        echo "\n<!-- 出力バッファリングの最終処理状態です -->\n";
34        // バッファの内容を小文字に変換し、識別子を追加して返します。
35        return strtolower($buffer) . "\n--- END ---\n";
36    }
37}
38
39// 出力バッファリングを開始し、カスタムハンドラ関数を登録します。
40// これ以降の echo や print の出力は、直接ブラウザには送られず、
41// 内部バッファに蓄積されます。
42ob_start('myOutputHandler');
43
44echo "Hello, PHP Output Buffering!\n";
45echo "This is a demonstration of custom output handler.\n";
46echo "The content will be processed by myOutputHandler function.";
47
48// ob_end_flush() を呼び出すと、蓄積されたバッファの内容が
49// myOutputHandler 関数に渡され、その戻り値が実際に出力されます。
50// これにより、上記の echo 文の内容が加工されてブラウザに表示されます。
51ob_end_flush();
52
53// ob_end_flush() が実行された後なので、この echo は直接出力されます。
54echo "\n--- Output buffering finished. This line is direct output. ---\n";
55
56?>

PHP_OUTPUT_HANDLER_STARTEDは、PHPの出力バッファリング機能において、出力ハンドラ関数に渡される「状態フラグ」の一つとして利用される定数です。

PHPの出力バッファリングとは、echoやprintなどの出力を直接ブラウザに送らず、一時的に内部のバッファに貯めておく仕組みのことです。この機能はob_start()関数で開始され、貯められた内容を加工するための「出力ハンドラ関数」を登録することができます。

この定数は、出力ハンドラ関数が呼び出された際に、現在のバッファリングが「開始された状態」であることや、ハンドラが「最初に呼び出された時」であることを示します。サンプルコードのmyOutputHandler関数では、出力ハンドラに渡される第二引数$flagsとPHP_OUTPUT_HANDLER_STARTEDをビット演算子「&」で比較することで、出力バッファリングが開始された初期段階であるかどうかを判断しています。

この判断に基づいて、初期段階ではバッファの内容を大文字に、それ以外の最終処理段階では小文字に変換するといったように、バッファの加工処理を分岐させています。最終的にob_end_flush()が実行されると、蓄積されたバッファ内容が出力ハンドラ関数によって加工され、その結果が実際の出力となります。

このようにPHP_OUTPUT_HANDLER_STARTEDを利用することで、出力バッファリングの特定の段階に応じた、よりきめ細やかな出力制御を実現できます。