PHP: ob_start

説明

function ob_start(?callable $callback = null, int $chunk_size = 0, int $flags = PHP_OUTPUT_HANDLER_STDFLAGS): bool

この関数は出力のバッファリングをオンにします。出力のバッファリングが有効な間は、スクリプトからの出力は送信されず、代わりに内部バッファに保存されます。どの出力が影響を受けるのかについてはどの出力をバッファするのか？を参照ください。

出力バッファはスタッカブルです。つまり、他のバッファがアクティブな間に ob_start() をコールできます。複数の出力バッファがアクティブの場合、出力はネストした順番でそれぞれのバッファを通して逐次フィルタ処理されます。詳細は出力バッファをネストさせるを参照ください。

出力バッファの詳細な説明はユーザーレベルの出力バッファを参照ください。

パラメータ

callback

オプションの callback として、 callable を指定できます。 null を渡すことでバイパスすることもできます。

callback は、出力バッファがフラッシュ (送信) または消去されたとき、あるいはスクリプトの最後に出力バッファがフラッシュされる際にコールされます。

callback のシグネチャは、次のとおりです。

function handler(string $buffer, int $phase = ?): string

buffer: 出力バッファの内容。
phase: PHP_OUTPUT_HANDLER_* 定数のビットマスク。詳細は出力ハンドラに渡されるフラグを参照ください。

callback が false を返すと、バッファの内容が返されます。詳細は出力ハンドラの戻り値を参照ください。

警告

出力ハンドラの内部から次の関数をコールすると、致命的なエラー (fatal error) となります。 ob_clean(), ob_end_clean(), ob_end_flush(), ob_flush(), ob_get_clean(), ob_get_flush(), ob_start()。

callback (出力ハンドラ) の詳細は出力ハンドラおよび出力ハンドラを扱うを参照ください。

chunk_size

オプションのパラメータ chunk_size が渡された場合、バッファの長さが chunk_size バイト以上になる出力があった後で、バッファがフラッシュされます。デフォルト値は 0 で、これはバッファがオフになるまですべての出力がバッファリングされることを意味します。詳細はバッファサイズを参照ください。

flags

flags はビットマスクで、出力バッファ上でどんな操作ができるのかを制御します。デフォルトでは、出力バッファのクリーン、フラッシュ、削除がすべてできるようになっています。これは、出力バッファの制御フラグを経由して明示的に設定できます。詳細はバッファに対して可能な操作を参照ください。

各フラグが、次の表のように関数へのアクセスを制御します。

定数	関数
`PHP_OUTPUT_HANDLER_CLEANABLE`	ob_clean()
`PHP_OUTPUT_HANDLER_FLUSHABLE`	ob_flush()
`PHP_OUTPUT_HANDLER_REMOVABLE`	ob_end_clean(), ob_end_flush(), ob_get_clean(), ob_get_flush()

注意: PHP 8.4.0 より前のバージョンでは、flags パラメータに出力ハンドラのステータスフラグも指定可能でした。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ユーザー定義のコールバック関数の例

<?php

function callback($buffer)
{
  // apples を全て oranges に置換する
  return (str_replace("apples", "oranges", $buffer));
}

ob_start("callback");

?>
<html>
<body>
<p>It's like comparing apples to oranges.</p>
</body>
</html>
<?php

ob_end_flush();

?>

上の例の出力は以下となります。

<html>
<body>
<p>It's like comparing oranges to oranges.</p>
</body>
</html>

例2 削除不可能な出力バッファを作る例

<?php

ob_start(null, 0, PHP_OUTPUT_HANDLER_STDFLAGS ^ PHP_OUTPUT_HANDLER_REMOVABLE);

?>

参考

ob_get_contents() - 出力用バッファの内容を返す
ob_end_clean() - アクティブな出力用バッファをクリア(消去)し、出力のバッファリングをオフにする
ob_end_flush() - アクティブな出力用バッファをフラッシュ(送信)し、アクティブな出力バッファをオフにする
ob_implicit_flush() - 自動フラッシュをオンまたはオフにする
ob_gzhandler() - 出力バッファを gzip 圧縮するための ob_start コールバック関数
ob_iconv_handler() - 出力バッファハンドラとして文字エンコーディングを変換する
mb_output_handler() - 出力バッファ内で文字エンコーディングを変換するコールバック関数
ob_tidyhandler() - バッファを修正するための ob_start コールバック関数