用户级输出缓冲区可以从 PHP 代码中实现启动、操作和终止。每个都包含输出缓冲区和关联的输出处理函数。
可以通过使用 ob_start() 函数或设置 output_buffering 和 output_handler php.ini 配置来启用输出缓冲。虽然两者都可以创建输出缓冲区,但 ob_start() 更加灵活,因为接受用户定义的函数作为输出处理程序,并且还可以设置对缓冲区允许的操作(冲刷、清空、移除)。通过 ob_start() 开始的缓冲区将从调用该函数的行开始生效,而通过 output_buffering 开始的缓冲区将从脚本的第一行开始缓冲输出。
PHP 还自带了内置的 "URL-Rewriter"
输出处理程序,它会启动自己的输出缓冲区,并且任何时候最多只允许有两个实例运行(一个用于用户级别的
URL 重写,另一个用于透明 Session ID 支持)。这些缓冲区可以通过调用 output_add_rewrite_var() 函数或启用
session.use_trans_sid php.ini 设置来启动。
捆绑的 zlib
扩展有自己的输出缓冲区,可以使用
zlib.output_compression
php.ini 设置启用。
注意:
"URL-Rewriter"
的特殊之处在于同时只允许运行最多两个实例,但所有用户级输出缓冲区都使用 ob_start() 所使用的相同底层缓冲区,并通过自定义的输出处理函数来实现其功能。因此,它们的所有功能都可以由用户级代码模拟。
冲刷会发送并丢弃活动缓冲区中的内容。当输出的大小超过缓冲区大小时,或者在脚本结束时,又或者是调用了 ob_flush()、ob_end_flush() 或 ob_get_flush() 函数时,会冲刷输出缓冲区。
调用 ob_end_flush() 或 ob_get_flush() 将关闭活跃的缓冲区。
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.
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().
Calling ob_end_clean() or ob_get_clean() will turn off the active buffer.
Output buffers can be turned off by calling ob_end_clean(), ob_end_flush(), ob_get_flush() or ob_get_clean().
Output buffers started without the
PHP_OUTPUT_HANDLER_REMOVABLE
flag
cannot be turned off and may generate an E_NOTICE
.
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.
If flushing of the buffer's contents is not desired, a custom output handler should be used to prevent flushing during shutdown.
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.
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
itsPHP_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.
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
itsPHP_OUTPUT_HANDLER_DISABLED
status flag is set.
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(), ob_clean(), ob_flush() or during PHP's shutdown process. Prior to PHP 8.4.0, this flag had no effect when calling ob_clean() or ob_flush().