説明

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

この関数は出力のバッファリングをオンにします。出力のバッファリングを有効にすると、 (ヘッダ以外の) スクリプトからの出力は実際には行われず、代わりに内部バッファに保存されます。

この内部バッファの内容は、ob_get_contents() を用いて文字列変数にコピーされます。内部バッファの内容を出力するには ob_end_flush() を使用します。 ob_end_clean() は、バッファの内容を出力せずに消去します。

警告

web サーバーによっては (例: Apache)、コールバック関数からコールされた際に、スクリプトの実行ディレクトリを変更するものがあります。コールバック関数の内部で chdir(dirname($_SERVER['SCRIPT_FILENAME'])) などと指定することで、これをもとに戻すことが可能です。

出力バッファはスタッカブルであり、このため、他の ob_start() がアクティブの間に ob_start() をコールすることが可能です。この場合、 ob_end_flush() を適切な回数コールするようにしてください。複数の出力コールバック関数がアクティブの場合、ネストした順番で逐次連続的に出力がフィルタ処理されます。

スクリプトが終了した際に、出力バッファリングがまだアクティブな場合、 PHP はバッファリングされた内容を自動的に出力します。

パラメータ

callback

オプションの引数 callback 関数を指定することが可能です。この関数は、パラメータとして文字列をとり、文字列を返します。このコールバック関数は、出力バッファがフラッシュ (送信) あるいは消去 (ob_flush(), ob_clean() あるいは同等の関数で) された場合、またはリクエストの最後にブラウザに出力をフラッシュする際にコールされます。 callback がコールされた際に、この関数は出力バッファの内容をパラメータとして受け取ります。このコールバック関数は、新規の出力バッファを実際に出力される結果として返す必要があり、この結果はブラウザに送信されます。 callback がコール可能な関数ではない場合は false を返します。コールバックのシグネチャは、次のとおりです。

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

buffer: 出力バッファの内容。
phase: PHP_OUTPUT_HANDLER_* 定数のビットマスク

callback が false を返すと、元の入力がそのままブラウザに送信されます。

callback パラメータに null 値を渡すと、これをバイパスすることができます。

ob_end_clean()、 ob_end_flush()、ob_clean()、 ob_flush() および ob_start() をコールバック関数の内部からコールすることはできません。実際にコールした際の挙動は未定義です。バッファの内容を消去したい際には、コールバック関数から "" (空文字列) を返してください。同じく、print_r($expression, true) や highlight_file($filename, true) のような出力バッファリング関数も、コールバック関数の内部からコールすることはできません。

注意:
Web ページの圧縮をサポートする圧縮 gz エンコードされたデータの Web ブラウザへの送信を容易にするために ob_gzhandler() が存在します。 ob_gzhandler() は、ブラウザが受け入れる content encoding の型を調べ、それに基づいて出力を返します。

chunk_size

オプションのパラメータ chunk_size が渡された場合、バッファの長さが chunk_size バイトを超えるたびに、出力の後でバッファがフラッシュされます。デフォルト値は 0 で、これは出力関数がコールされるのが出力バッファが閉じたときだけであることを意味します。

flags

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

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

定数関数

PHP_OUTPUT_HANDLER_CLEANABLE ob_clean()

PHP_OUTPUT_HANDLER_FLUSHABLE ob_end_flush() ob_flush()

PHP_OUTPUT_HANDLER_REMOVABLE ob_end_clean(), ob_end_flush(), ob_get_clean(), ob_get_flush()

定数	関数
`PHP_OUTPUT_HANDLER_CLEANABLE`	ob_clean()
`PHP_OUTPUT_HANDLER_FLUSHABLE`	ob_end_flush() 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 コールバック関数