ob_start
出力のバッファリングを有効にする
説明
bool ob_start(callablenull $callback = null, int $chunk_size = 0, int $flags = PHP_OUTPUT_HANDLER_STDFLAGS)
この内部バッファの内容は、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 を返します。
コールバックのシグネチャは、次のとおりです。
string handler(string $buffer, int $phase = ?)
-
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 はビットマスクで、出力バッファ上でどんな操作ができるのかを制御します。
デフォルトでは、出力バッファのクリーン、フラッシュ、削除がすべてできるようになっています。
これは、
出力バッファの制御フラグ
を経由して明示的に設定できます。
詳細は バッファに対して可能な操作
を参照ください。
各フラグが、次の表のように関数へのアクセスを制御します。
戻り値
成功した場合に 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
- ob_iconv_handler
- mb_output_handler
- ob_tidyhandler