Пользовательские буферы вывода разрешается запускать, манипулировать ими и завершать из PHP-кода. Каждый из этих буферов состоит из буфера вывода и связанной с ним функции обработчика вывода.
Буферизацию вывода включают вызовом функции ob_start() или установкой в файле php.ini параметров директивам output_buffering и output_handler. Хотя оба способа умеют создавать буферы вывода, функция ob_start() гибче, поскольку принимает в качестве обработчиков вывода пользовательские функции и умеет задавать операции, разрешенные для буфера (сброс, очистка, удаление). Буферы, которые запустили функцией ob_start(), активируются с той строки, на которой вызвали функцию, тогда как те, которые запустили директивой output_buffering, буферизуют вывод начиная с первой строки скрипта.
PHP также поставляется со встроенным обработчиком вывода URL-Rewriter
,
который запускает свой буфер вывода и разрешает
запускать одновременно до двух его экземпляров
(один для перезаписи URL-адресов на уровне пользователя
и ещё один для поддержки прозрачного идентификатора сессии).
Эти буферы запускают вызовом функции
output_add_rewrite_var()
и (или) включением
директивы session.use_trans_sid
в файле php.ini.
В модуль zlib
, который входит в комплект PHP, интегрировали свой
буфер вывода, который включают директивой
zlib.output_compression
в файле php.ini.
Замечание: Хотя обработчик
URL-Rewriter
и выделяется тем, что разрешает запускать одновременно только до двух своих экземпляров, пользовательские буферы вывода работают с теми же базовыми буферами, которые использует функция ob_start(), а их функциональность реализуется пользовательской функцией обработчика вывода. Поэтому их функциональность в состоянии сымитировать пользовательский код.
Сброс отправляет и удаляет содержимое активного буфера. Буферы вывода сбрасываются, когда размер вывода превышает размер буфера, скрипт завершает работу или вызываются функции ob_flush(), ob_end_flush() или ob_get_flush().
Вызов функций ob_end_flush() или ob_get_flush() отключит активный буфер.
Сброс буферов также сбросит возвращаемое обработчиком вывода значение, которое обработчик вывода умеет изменять, и если так, значение будет отличаться от содержимого буфера. Например, передача в обработчик вывода функции ob_gzhandler() приведёт к сжатию данных вывода и сбросу сжатого вывода.
Содержимое активного буфера получают вызовом функций ob_get_contents(), ob_get_clean() или ob_get_flush().
Если нужен только размер содержимого буфера, функции ob_get_length() или ob_get_status() вернут размер содержимого в байтах.
Вызов функций ob_get_clean() или ob_get_flush() отключит активный буфер после возврата его содержимого.
Содержимое активного буфера очищают вызовом функций ob_clean(), ob_end_clean() или ob_get_clean().
Вызов функций ob_end_clean() или ob_get_clean() отключит активный буфер вывода.
Буферы вывода отключают вызовом функций ob_end_clean(), ob_end_flush(), ob_get_flush() или ob_get_clean().
Буферы вывода, которые запустили без флага
PHP_OUTPUT_HANDLER_REMOVABLE
,
нельзя отключить, а попытка удалить такие буферы выдаст ошибку уровня E_NOTICE
.
Каждый буфер вывода, который не закрыли до конца скрипта или вызовом конструкции exit(), сбросит и отключит процесс завершения работы PHP. Буферы сбрасываются и отключаются в порядке, обратном их запуску. Буфер, который запустили последним, будет первым, а буфер, который запустили первым, сбросится и отключится в последнюю очередь.
Пользовательский обработчик вывода активируют, чтобы предотвратить сброс буфера вывода при завершении работы PHP, если сброс содержимого буферов не нужен.
Если в обработчике вывода выбрасывается неперехваченное исключение,
программа завершается, а процесс завершения работы вызывает обработчик,
затем выводится сообщение об ошибке Uncaught Exception
.
Если в обработчике вывода, который вызвали функцией ob_flush(), ob_end_flush() или ob_get_flush(), выбрасывается неперехваченное исключение, содержимое буфера сбрасывается перед сообщением об ошибке.
Если в обработчике вывода неперехваченное исключение выбрасывается при выключении, обработчик завершается, ни содержимое буфера, ни сообщение об ошибке не сбрасываются.
Замечание: Если обработчик вывода выбрасывает исключение, PHP устанавливает для обработчика флаг состояния
PHP_OUTPUT_HANDLER_DISABLED
.
Если в обработчике вывода выдаётся неустранимая ошибка, программа продолжает выполняться.
Если в обработчике, который вызвали функцией
ob_flush(), ob_end_flush()
или ob_get_flush(),
возникает неустранимая ошибка,
буфер сбрасывает данные, которые вернул обработчик.
Если обработчик возвращает значение false
, сбрасываются буфер и сообщение об ошибке.
Если возвращает другое значение, возвращаемое обработчиком значение сбрасывается,
но не сообщение об ошибке.
Замечание: Если обработчик возвращает значение
false
PHP устанавливает для обработчика флаг состоянияPHP_OUTPUT_HANDLER_DISABLED
.
Если в обработчике вывода возникает фатальная ошибка, программа завершается, а процесс завершения работы вызывает обработчик, затем сбрасывается сообщение об ошибке.
Если в обработчике вывода, который вызвали функцией ob_flush(), ob_end_flush() или ob_get_flush(), возникает фатальная ошибка, содержимое буферов сбрасывается перед сообщением об ошибке.
Если в обработчике вывода фатальная ошибка возникает при выключении, программа завершается без сброса буфера или сообщения об ошибке.
При конкретных обстоятельствах выходные данные, которые создаются в обработчике, сбрасываются вместе с содержимым буфера. Этот вывод не добавляется в буфер и не становится строкой, которую возвращает функция ob_get_flush().
Если во время операций сброса (при вызове функций ob_flush(),
ob_end_flush(), ob_get_flush()
и при завершении работы)
возвращаемое значение обработчика равно false
,
содержимое буфера сбрасывается, а затем идёт вывод.
Если обработчик не вызывается при завершении работы,
то обработчик выбрасывает исключение;
вызов конструкции exit()
ведёт себя так же.
Замечание: Если обработчик возвращает значение
false
, PHP устанавливает для обработчика флаг состоянияPHP_OUTPUT_HANDLER_DISABLED
.
PHP устанавливает
флаги состояния обработчика
битовой маски флагов (flags
) буфера
каждый раз при вызове обработчика вывода
и делает их частью флагов (flags
), которые возвращает
функция ob_get_status().
Если обработчик успешно выполняется и не возвращает значение false
,
PHP устанавливает флаги состояния PHP_OUTPUT_HANDLER_STARTED
и PHP_OUTPUT_HANDLER_PROCESSED
.
Если обработчик возвращает значение false
или выбрасывает исключение во время работы,
PHP устанавливает флаги состояния PHP_OUTPUT_HANDLER_STARTED
и PHP_OUTPUT_HANDLER_DISABLED
.
Замечание: Обработчик не будет запускаться при вызове функций ob_end_clean(), ob_end_flush(), ob_get_clean(), ob_get_flush(), ob_clean(), ob_flush() или при завершении процесса работы PHP, если для обработчика установили значение
PHP_OUTPUT_HANDLER_DISABLED
. До PHP 8.4.0 этот флаг не влиял на вызов функций ob_clean() и ob_flush().