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

Copy
1<?php
2
3/**
4 * PHP_OUTPUT_HANDLER_FLUSHABLE 定数の使用例。
5 *
6 * この定数は、ob_start() 関数に渡すフラグの一つです。
7 * 出力バッファリングハンドラがフラッシュ可能であることを示し、
8 * ob_flush() や ob_end_flush() 関数でバッファの内容を出力（フラッシュ）
9 * できるようにします。
10 */
11function demonstratePhpOutputHandlerFlushable(): void
12{
13    // PHP_OUTPUT_HANDLER_FLUSHABLE 定数の値を出力します。
14    // この定数は整数値です。
15    echo "PHP_OUTPUT_HANDLER_FLUSHABLE の値: " . PHP_OUTPUT_HANDLER_FLUSHABLE . PHP_EOL;
16
17    echo "--- 出力バッファリング開始 ---" . PHP_EOL;
18
19    // 出力バッファリングを開始します。
20    // PHP_OUTPUT_HANDLER_FLUSHABLE フラグは、バッファの内容を
21    // 途中でフラッシュできることを示します。
22    // 通常、他のフラグ (例: PHP_OUTPUT_HANDLER_CLEANABLE) と組み合わせて使用されます。
23    ob_start(
24        null, // コールバック関数は指定しません。
25        0,    // デフォルトのバッファサイズを使用します。
26        PHP_OUTPUT_HANDLER_FLUSHABLE | PHP_OUTPUT_HANDLER_CLEANABLE
27    );
28
29    echo "バッファに書き込み中... (1回目)" . PHP_EOL;
30
31    // ob_flush() を呼び出すと、現在バッファに溜まっている内容が
32    // 親のバッファ、または最終的な出力先へ送られます。
33    // PHP_OUTPUT_HANDLER_FLUSHABLE フラグが設定されていない場合、この操作はエラーとなります。
34    echo "ob_flush() でバッファの内容をフラッシュします。" . PHP_EOL;
35    ob_flush();
36
37    echo "バッファに書き込み中... (2回目)" . PHP_EOL;
38
39    // ob_end_flush() を呼び出してバッファリングを終了し、
40    // 残りの内容を全て出力します。
41    echo "ob_end_flush() でバッファリングを終了し、全ての内容を出力します。" . PHP_EOL;
42    ob_end_flush();
43
44    echo "--- 出力バッファリング終了 ---" . PHP_EOL;
45}
46
47// 関数を実行して、PHP_OUTPUT_HANDLER_FLUSHABLE の動作を確認します。
48demonstratePhpOutputHandlerFlushable();
49
50?>

PHP_OUTPUT_HANDLER_FLUSHABLEは、PHPの出力バッファリング機能で利用される内部定数です。この定数は整数型（int）の値を持ち、出力バッファリングハンドラが「フラッシュ可能である」ことを示します。

この定数は主にob_start()関数の第三引数（フラグ）として使用されます。ob_start()にこの定数を渡すことで、開始された出力バッファの内容を、ob_flush()関数やob_end_flush()関数を使って途中で現在の出力先へ送出（フラッシュ）できるようになります。もしこの定数が指定されていない状態でob_flush()を呼び出すと、エラーが発生する可能性があります。

サンプルコードでは、PHP_OUTPUT_HANDLER_FLUSHABLEの具体的な整数値を確認した後、ob_start()関数にPHP_OUTPUT_HANDLER_FLUSHABLEとPHP_OUTPUT_HANDLER_CLEANABLEを組み合わせて渡しています。これにより、バッファに書き込まれた内容をob_flush()で中間的に出力し、その後さらに書き込みを行い、最終的にob_end_flush()でバッファリングを終了させつつ残りの内容を全て出力する、という一連の処理が正しく実行されることを示しています。この定数は、バッファの内容を段階的に出力したい場合に必要不可欠なフラグです。

Copy
1<?php
2
3/**
4 * カスタム出力ハンドラ関数
5 *
6 * 出力バッファの内容を加工し、ハンドラに設定されたフラグに基づいてコメントを追加します。
7 * この関数は ob_start() のコールバックとして使用されます。
8 *
9 * @param string $buffer 現在の出力バッファの内容
10 * @param int $flags 出力ハンドラに設定されたフラグ。例: PHP_OUTPUT_HANDLER_FLUSHABLE, PHP_OUTPUT_HANDLER_CLEANABLE
11 * @return string 加工されたバッファの内容
12 */
13function myOutputHandler(string $buffer, int $flags): string
14{
15    $processedBuffer = "--- Custom Handler Processing ---\n";
16
17    // PHP_OUTPUT_HANDLER_FLUSHABLE 定数が設定されているか確認します。
18    // このフラグは、ハンドラがバッファを部分的にフラッシュできることを示します。
19    if ($flags & PHP_OUTPUT_HANDLER_FLUSHABLE) {
20        $processedBuffer .= "[FLUSHABLE] This handler supports partial flushing of the buffer.\n";
21    }
22
23    // キーワードに関連する PHP_OUTPUT_HANDLER_CLEANABLE 定数が設定されているか確認します。
24    // このフラグは、ハンドラがバッファの内容をクリアできることを示します。
25    if ($flags & PHP_OUTPUT_HANDLER_CLEANABLE) {
26        $processedBuffer .= "[CLEANABLE] This handler supports clearing the buffer content.\n";
27    }
28
29    $processedBuffer .= "Original Content Captured by Handler:\n";
30    $processedBuffer .= $buffer;
31    $processedBuffer .= "---------------------------------\n";
32
33    return $processedBuffer;
34}
35
36// -----------------------------------------------------------------------------
37// PHP_OUTPUT_HANDLER_FLUSHABLE と PHP_OUTPUT_HANDLER_CLEANABLE の使用例
38// -----------------------------------------------------------------------------
39
40echo "--- Start of Output Buffer Demonstration ---\n";
41
42// ob_start() で出力バッファリングを開始し、カスタムハンドラを設定します。
43// 第3引数 (flags) に PHP_OUTPUT_HANDLER_FLUSHABLE と PHP_OUTPUT_HANDLER_CLEANABLE を
44// ビットOR演算子 (|) で組み合わせて渡します。
45// これにより、この出力ハンドラはフラッシュもクリアも可能な状態になります。
46ob_start('myOutputHandler', 0, PHP_OUTPUT_HANDLER_FLUSHABLE | PHP_OUTPUT_HANDLER_CLEANABLE);
47
48echo "First line of text.\n";
49echo "Second line of text.\n";
50
51// ob_flush() を呼び出すと、現在のバッファの内容が 'myOutputHandler' によって処理され、
52// 外部の出力バッファへ送られます。ただし、バッファリング自体は継続します。
53// ハンドラに PHP_OUTPUT_HANDLER_FLUSHABLE が設定されているため、この操作が可能です。
54echo "\n--- Calling ob_flush() to partially output the buffer ---\n";
55ob_flush();
56
57echo "Text added after ob_flush().\n";
58
59// ob_clean() を呼び出すと、現在のバッファの内容がすべて破棄されます。
60// バッファリング自体は継続します。
61// ハンドラに PHP_OUTPUT_HANDLER_CLEANABLE が設定されているため、この操作が可能です。
62echo "\n--- Calling ob_clean() to discard the buffer content ---\n";
63ob_clean(); // ここまでの "Text added after ob_flush().\n" は破棄されます。
64
65echo "Final text after ob_clean().\n";
66
67// ob_end_flush() で出力バッファリングを終了し、残っている最終的なバッファ内容を出力します。
68ob_end_flush();
69
70echo "\n--- End of Output Buffer Demonstration ---\n";

PHPでは、echoなどで出力される内容を一時的にメモリにためておく「出力バッファリング」という機能があります。ob_start()関数を使うとこのバッファリングを開始し、バッファにたまった内容を加工する「出力ハンドラ関数」を設定できます。

PHP_OUTPUT_HANDLER_FLUSHABLEは、この出力ハンドラ関数が、バッファの内容を部分的に外部へ出力できる（フラッシュできる）能力を持つことを示す整数定数です。この定数自体は整数値（int）です。また、関連するPHP_OUTPUT_HANDLER_CLEANABLEは、ハンドラがバッファの内容をすべて破棄できる（クリアできる）能力を示す別の整数定数です。

これらの定数は、ob_start()関数の第3引数として、出力ハンドラの特性を定義するフラグとして渡されます。例えば、サンプルコードではPHP_OUTPUT_HANDLER_FLUSHABLE | PHP_OUTPUT_HANDLER_CLEANABLEという形で、ハンドラにフラッシュとクリア両方の能力を付与しています。カスタムハンドラ関数myOutputHandlerは、$flags引数として受け取った整数値の中から、これらの定数が設定されているかビット演算で確認し、それぞれに応じた処理を行います。この$flags引数は、ハンドラに与えられた能力を示す整数値です。

ob_flush()関数は、PHP_OUTPUT_HANDLER_FLUSHABLEが設定されていれば、ハンドラを通して現在のバッファ内容を部分的に出力させます。ob_clean()関数は、PHP_OUTPUT_HANDLER_CLEANABLEが設定されていれば、ハンドラを通して現在のバッファ内容を破棄します。これにより、PHPの出力処理を柔軟に制御できます。