User-Level Output BuffersTable of Contents
User-level output buffers can be started, manipulated and terminated from PHP code. Each of these buffers includes an output buffer and an associated output handler function. Turning Output Buffering OnOutput 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
The bundled
Flushing, Accessing And Cleaning Buffer ContentsFlushing 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. Caution
Calling ob_end_flush or ob_get_flush will turn off the active buffer. Caution
Flushing buffers will flush the return value of the output handler which can differ from the contents of the buffer. For example, using ob_gzhandler will compress the output and flush the compressed output. 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. Caution
Calling ob_get_clean or ob_get_flush will turn off the active buffer after returning the its contents. The contents of the active buffer can be cleaned by calling ob_clean, ob_end_clean or ob_get_clean. Caution
Calling ob_end_clean or ob_get_clean will turn off the active buffer. Turning Buffers OffOutput buffers can be turned off by calling ob_end_clean, ob_end_flush, ob_get_flush or ob_get_clean. Warning
Output buffers started without the
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. Caution
If flushing of the buffer's contents is not desired, a custom output handler should be used to prevent flushing during shutdown. 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 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.
Errors Raised In Output HandlersIf 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
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 HandlersIn 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
Output Handler Status Flags
The
handler status flags
of the buffer's
|