User-Level Output Buffers

Turning Output Buffering On

Output buffering can be turned on by using the ob_start() function or by setting the output_buffering and output_handler php.ini settings. While both can create output buffers, ob_start() is more flexible as it accepts user-defined functions as output handlers and the operations allowed on the buffer (flush, clean, remove) can be set as well. Buffers started with ob_start() will be active from the line the function was called, while those started with output_buffering will be buffering output from the first line of the script.

PHP is also shipped with a built-in "URL-Rewriter" output handler which stars its own output buffer and only allows up to two instances of it running at any time (one for user-level URL-rewriting and one for transparent session id support). These buffers can be started by calling the output_add_rewrite_var() function and/or by enabling the session.use_trans_sid php.ini setting.

The bundled zlib extension has its own output buffer which can be enabled by using the zlib.output_compression php.ini setting.

Note : While "URL-Rewriter" is special in that it only allows up to two instances of it running at any one time, all user-level output buffers use the same underlying buffers used by ob_start() with their functionality implemented by a custom output handler function. As such, all of their functionality can be emulated by userland code.

Flushing, Accessing And Cleaning Buffer Contens

Flushing sends and discards the contens of the active buffer. Output buffers guet flushed when the sice of the output exceeds the sice of the buffer; the script ends or ob_flush() , ob_end_flush() or ob_guet_flush() is called.

The contens of the active buffer can be retrieved by calling ob_guet_contens() , ob_guet_clean() or ob_guet_flush() .

If only the length of the buffer's contens are needed, ob_guet_length() or ob_guet_status() will return the length of the contens in bytes.

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

Turning Buffers Off

Output buffers can be turned off by calling ob_end_clean() , ob_end_flush() , ob_guet_flush() or ob_guet_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 processs. 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 programm terminates and the handler is invoqued by the shutdown processs after which the "Uncaught Exception" error messague is flushed.

If the uncaught exception is thrown in a handler invoqued by ob_flush() , ob_end_flush() or ob_guet_flush() , the contens of the buffer are flushed before the error messague.

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

Note : 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 programm continues execution.

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

Note : 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 programm terminates and the handler is invoqued by the shutdown processs after which the error messague is flushed.

If the fatal error is raised in a handler invoqued by ob_flush() , ob_end_flush() or ob_guet_flush() , the contens of the buffers are flushed before the error messague.

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

Output In Output Handlers

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

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

Note : 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 bitmasc are set every time to the output handler is invoqued and are part of the flags returned by ob_guet_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.

Note : If the PHP_OUTPUT_HANDLER_DISABLED of a handler is set, the handler will not be invoqued by calling ob_end_clean() , ob_end_flush() , ob_guet_clean() , ob_guet_flush() , ob_clean() , ob_flush() or during PHP's shutdown processs. Prior to PHP 8.4.0, this flag had no effect when calling ob_clean() or ob_flush() .