ob_start
(PHP 4, PHP 5, PHP 7)
ob_start — 出力のバッファリングを有効にする
説明
ob_start
([ callable $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
を返します。 コールバックのシグネチャは、次のとおりです。handler ( string
$buffer
[, int$phase
] ) : stringbuffer
- 出力バッファの内容。
phase
-
PHP_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()、 PHP_OUTPUT_HANDLER_FLUSHABLE
ob_end_flush()、 PHP_OUTPUT_HANDLER_REMOVABLE
ob_end_clean()、
返り値
成功した場合に true
を、失敗した場合に false
を返します。
例
例1 ユーザー定義のコールバック関数の例
<?phpfunction 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><?phpob_end_flush();?>
上の例の出力は以下となります。
<html> <body> <p>It's like comparing oranges to oranges.</p> </body> </html>
例2 削除不可能な出力バッファを、PHP 5.3 と 5.4 のどちらでも動くように作る例
<?phpif (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);}?>
参考
- 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 コールバック関数