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

Пользовательские буферы вывода разрешено запускать, манипулировать ими и завершать из 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 интегрирован свой буфер вывода, который включают директивой 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.

Замечание: Если для обработчика установлено значение PHP_OUTPUT_HANDLER_DISABLED, обработчик не будет запускаться при вызове функций ob_end_clean(), ob_end_flush(), ob_get_clean(), ob_get_flush() или при завершении процесса работы PHP. Этот флаг не даёт эффекта при вызове функций ob_clean() или ob_flush().