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

## Содержание

- Какой вывод буферизуется?
- Вложенные буферы вывода
- Размер буфера
- Операции, разрешённые для буферов
- Обработчики вывода
- Работа с обработчиками вывода
- Флаги, передаваемые обработчикам вывода
- Значения, которые возвращает обработчик вывода

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

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open