(PHP 4, PHP 5, PHP 7)
ob_start — 出力のバッファリングを有効にする
$output_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() を適切な回数コールするようにしてください。 複数の出力コールバック関数がアクティブの場合、 ネストした順番で逐次連続的に出力がフィルタ処理されます。
output_callback
オプションの引数 output_callback
関数を指定することが可能です。この関数は、パラメータとして文字列をとり、
文字列を返します。このコールバック関数は、
出力バッファがフラッシュ (送信) あるいは消去
(ob_flush(), ob_clean()
あるいは同等の関数で) された場合、
またはリクエストの最後にブラウザに出力をフラッシュする際にコールされます。
output_callback がコールされた際に、
この関数は出力バッファの内容をパラメータとして受け取ります。このコールバック関数は、
新規の出力バッファを実際に出力される結果として返す必要があり、
この結果はブラウザに送信されます。
output_callback がコール可能な関数ではない場合は
FALSE を返します。
コールバックのシグネチャは、次のとおりです。
$buffer
[, int $phase
] ) : stringbufferphasePHP_OUTPUT_HANDLER_* のビットマスク。
output_callback が FALSE
を返すと、元の入力がそのままブラウザに送信されます。
output_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 で、これは出力関数がコールされるのが
出力バッファが閉じたときだけであることを意味します。
PHP 5.4.0 より前のバージョンでは、1 にも特別な意味があり、 これを指定するとチャンクサイズが 4096 バイトになります。
flags
flags はビットマスクで、出力バッファ上でどんな操作ができるのかを制御します。
デフォルトでは、出力バッファのクリーン、フラッシュ、削除がすべてできるようになっています。
これは、明示的に
PHP_OUTPUT_HANDLER_CLEANABLE |
PHP_OUTPUT_HANDLER_FLUSHABLE |
PHP_OUTPUT_HANDLER_REMOVABLE と設定したり、あるいは短縮形で
PHP_OUTPUT_HANDLER_STDFLAGS と設定したりするのと同じです。
各フラグが、次の表のように関数へのアクセスを制御します。
| 定数 | 関数 |
|---|---|
PHP_OUTPUT_HANDLER_CLEANABLE |
ob_clean()、 ob_end_clean() および ob_get_clean() |
PHP_OUTPUT_HANDLER_FLUSHABLE |
ob_end_flush()、 ob_flush() および ob_get_flush() |
PHP_OUTPUT_HANDLER_REMOVABLE |
ob_end_clean()、 ob_end_flush() および ob_get_flush() |
成功した場合に TRUE を、失敗した場合に FALSE を返します。
| バージョン | 説明 |
|---|---|
| 7.0.0 |
ob_start() を出力バッファコールバックの内部で使う場合、
この関数は E_ERROR の代わりに
E_RECOVERABLE_ERROR を発行して、カスタムエラーハンドラで対応できるようにします。
|
| 5.4.0 |
ob_start() の三番目のパラメータが
boolean erase
(これを FALSE にすると、スクリプトの実行が終了するまで出力バッファを削除できなくなります)
から integer flags に変わりました。
残念ながら、そのせいで API の互換性が崩れてしまい。
PHP 5.4.0 より前のバージョンで三番目のパラメータを使っていたコードは、
そのままでは期待通りに動かなくなりました。
この例
のようにして、両方のバージョンでの互換性を保つ必要があります。
|
| 5.4.0 | チャンクサイズに 1 を指定したときに、 1 バイトのチャンクを出力バッファに送るようになりました。 |
| 4.3.2 |
output_callback を実行することができない場合に
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 5.3 と 5.4 のどちらでも動くように作る例
<?php
if (version_compare(PHP_VERSION, '5.4.0', '>=')) {
ob_start(null, 0, PHP_OUTPUT_HANDLER_STDFLAGS ^
PHP_OUTPUT_HANDLER_REMOVABLE);
} else {
ob_start(null, 0, false);
}
?>