ユーザーレベルの出力バッファ

出力バッファリングをオンにする

出力バッファリングは、php.ini 設定 output_buffering と output_handler を設定するか、ob_start() 関数を使うことでオンにできます。 これらは両方、出力バッファを生成できますが、 ob_start() の方がより柔軟です。 なぜなら、出力ハンドラをユーザー定義関数として受け入れますし、 (フラッシュ、クリーン、削除 のような) バッファに対する操作もできるからです。 ob_start() で開始したバッファは、 それをコールした行からアクティブになりますが、 output_buffering を使って開始したバッファは、スクリプトの最初の行から、出力をバッファします。

PHP は組み込みの "URL-Rewriter" 出力ハンドラをバンドルしています。 このハンドラは、自分の出力バッファを開始します。 同時に実行できるのはふたつです(1つはユーザレベルのURL書き換えと、 透過的なセッションIDサポートのためのもの) 。 これらのバッファは、output_add_rewrite_var() 関数をコールするか、php.ini 設定 session.use_trans_sid を有効にすることで開始できます。

バンドルされている zlib 拡張モジュールは、 独自の出力バッファを持っています。 この出力バッファは、php.ini 設定 zlib.output_compression を使うことで有効にできます。

注意: 一度に二つまでしか実行できないという意味で、 "URL-Rewriter" は特別なものです。 しかし、すべてのユーザレベルの出力バッファは、 カスタムの出力ハンドラ関数を指定して ob_start() をコールすることで開始した既存のバッファと同じものを使います。 そのため、すべての機能はユーザランドのコードでエミュレートすることができます。

Flushing, Accessing And Cleaning Buffer Contents

Flushing sends and discards the contents of the active buffer. Output buffers get flushed when the size of the output exceeds the size of the buffer; the script ends or ob_flush(), ob_end_flush() or ob_get_flush() is called.

The contents of the active buffer can be retrieved by calling ob_get_contents(), ob_get_clean() or ob_get_flush().

If only the length of the buffer's contents are needed, ob_get_length() or ob_get_status() will return the length of the contents in bytes.

The contents of the active buffer can be cleaned by calling ob_clean(), ob_end_clean() or ob_get_clean().

Turning Buffers Off

Output buffers can be turned off by calling ob_end_clean(), ob_end_flush(), ob_get_flush() or ob_get_clean().

Every output buffer that has not been closed by the end of the script or when exit() is called will be flushed and turned off by PHP's shutdown process. The buffers will be flushed and turned off in reverse order of their starting up. The last buffered started will be first, the first buffer started will be last to be flushed and turned off.

Exceptions Thrown In Output Handlers

If an uncaught exception is thrown in an output handler the program terminates and the handler is invoked by the shutdown process after which the "Uncaught Exception" error message is flushed.

If the uncaught exception is thrown in a handler invoked by ob_flush(), ob_end_flush() or ob_get_flush(), the contents of the buffer are flushed before the error message.

If an uncaught exception is thrown in an output handler during shutdown, the handler is terminated and neither the contents of the buffer nor the error message is flushed.

注意: If a handler throws an exception its PHP_OUTPUT_HANDLER_DISABLED status flag is set.

Errors Raised In Output Handlers

If a non-fatal error is raised in an output handler the program continues execution.

If the non-fatal error is raised in a handler invoked by ob_flush(), ob_end_flush() or ob_get_flush(), the buffer flushes certain data depending on the return value of the handler. If the handler returns false the buffer and the error message are flushed. If the returns anything else the handler return value is flushed but not the error message.

注意: If a handler returns false its PHP_OUTPUT_HANDLER_DISABLED status flag is set.

If a fatal error is raised in an output handler the program terminates and the handler is invoked by the shutdown process after which the error message is flushed.

If the fatal error is raised in a handler invoked by ob_flush(), ob_end_flush() or ob_get_flush(), the contents of the buffers are flushed before the error message.

If a fatal error is raised in an output handler during shutdown the program terminates without flushing the buffer or the error message.

Output In Output Handlers

In specific circumstances, output produced in the handler is flushed along with the contents of the buffer. This output is not appended to the buffer and is not part of the string returned by ob_get_flush().

During flush operations (calling ob_flush(), ob_end_flush(), ob_get_flush() and during shutdown) if the return value of a handler is false the contents of the buffer are flushed followed by the output. If the handler is not invoked during shutdown the handler throwing an exception or exit() being called results in the same behavior.

注意: If a handler returns false its PHP_OUTPUT_HANDLER_DISABLED status flag is set.

Output Handler Status Flags

The handler status flags of the buffer's flags bitmask are set every time to the output handler is invoked and are part of the flags returned by ob_get_status(). If the handler successfully executes and does not return false, PHP_OUTPUT_HANDLER_STARTED and PHP_OUTPUT_HANDLER_PROCESSED is set. If the handler returns false or throws an exception while executing, PHP_OUTPUT_HANDLER_STARTED and PHP_OUTPUT_HANDLER_DISABLED is set.

注意: If the PHP_OUTPUT_HANDLER_DISABLED of a handler is set, the handler will not be invoked by calling ob_end_clean(), ob_end_flush(), ob_get_clean(), ob_get_flush() or during PHP's shutdown process. This flag has no effect on when calling ob_clean() or ob_flush().