Пользовательские буферы вывода

Включение буферизации вывода

Буферизацию вывода включают вызовом функции 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_get_contents(), ob_get_clean() или ob_get_flush().

Если нужен только размер содержимого буфера, функции ob_get_length() или ob_get_status() вернут размер содержимого в байтах.

Содержимое активного буфера очищают вызовом функций ob_clean(), ob_end_clean() или ob_get_clean().

Отключение буферов

Буферы вывода отключают вызовом функций ob_end_clean(), ob_end_flush(), ob_get_flush() или ob_get_clean().

Каждый буфер вывода, который не закрыли до конца скрипта или вызовом конструкции exit(), сбросит и отключит процесс завершения работы 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().