Эта функция включает буферизацию вывода. Если буферизация вывода активна, вывод скрипта не высылается (кроме заголовков), а сохраняется во внутреннем буфере.

Содержимое этого внутреннего буфера может быть скопировано в строковую переменную, используя ob_get_contents(). Для вывода содержимого внутреннего буфера следует использовать ob_end_flush(). В качестве альтернативы можно использовать ob_end_clean() для уничтожения содержимого буфера.

Внимание

Некоторые web-сервера (например Apache) изменяют рабочую директорию скрипта, когда вызывается callback-функция. Вы можете вернуть ее назад, используя chdir(dirname($_SERVER['SCRIPT_FILENAME'])) в callback-функции.

Буферы вывода помещаются в стек, то есть допускается вызов ob_start() после вызова другой активной ob_start(). При этом необходимо вызывать ob_end_flush() соответствующее количество раз. Если активны несколько callback-функций, вывод последовательно фильтруется для каждой из них в порядке вложения.

Список параметров

output_callback

Можно задать необязательный параметр output_callback. Эта функция принимает строку в виде аргумента и должна также вернуть строку. Она вызывается при сбросе (отправке) или очистке (с помощью ob_flush(), ob_clean() или подобных функций) или если буфер вывода сбрасывается в браузер по окончанию запроса. При вызове функции output_callback, она получает содержимое буфера и должна вернуть обновленное содержимое для буфера вывода, который будет отправлен браузеру. Если output_callback не является допустимой функцией, то документируемая функция вернет FALSE. Описание функции для этого параметра:

string handler ( string $buffer [, int $phase ] )

buffer: Содержимое буфера вывода.
phase: Битовая маска констант PHP_OUTPUT_HANDLER_*.

Если output_callback вернет FALSE, то оригинальная информация отправится в браузер без изменений.

Параметр output_callback может быть игнорирован передачей значения NULL.

ob_end_clean(), ob_end_flush(), ob_clean(), ob_flush() и ob_start() не могут вызываться из callback-функций, так как их поведение непредсказуемо. Если вы хотите удалить содержимое буфера, то верните "" (пустую строку) из callback-функции. Вы так же не можете вызывать функции print_r($expression, true) или highlight_file($filename, true) из callback-функций буферизации вывода.

Замечание:
В PHP 4.0.4 функция ob_gzhandler() была введена для облегчения отправки gz-кодированных данных web-браузерам, поддерживающим сжатые web-страницы. ob_gzhandler() определяет тип кодировки содержимого, принимаемый браузером, и возвращает вывод соответствующим образом.

chunk_size

Если передан не обязательный параметр chunk_size, то буфер буден сброшен после любого вывода превышающего или равного по размеру chunk_size. Значение по умолчанию 0 означает, что функция вывода будет вызвана, когда буфер будет закрыт.

До PHP 5.4.0, значение 1 было специальным значением, которое устанавливало параметр chunk_size в 4096.

flags

Параметр flags является битовой маской, которая управляет операциями, которые можно совершать над буфером вывода. По умолчанию она позволяет буферу вывода быть очищенным, сброшенным и удаленным, что равносильно значению PHP_OUTPUT_HANDLER_CLEANABLE | PHP_OUTPUT_HANDLER_FLUSHABLE | PHP_OUTPUT_HANDLER_REMOVABLE, или PHP_OUTPUT_HANDLER_STDFLAGS как сокращение этой комбинации.

Each flag controls access to a set of functions, as described below:

Константа	Функции
`PHP_OUTPUT_HANDLER_CLEANABLE`	ob_clean(), ob_end_clean(), и ob_get_clean().
`PHP_OUTPUT_HANDLER_FLUSHABLE`	ob_end_flush(), ob_flush(), и ob_get_flush().
`PHP_OUTPUT_HANDLER_REMOVABLE`	ob_end_clean(), ob_end_flush(), и ob_get_flush().

Возвращаемые значения

Возвращает TRUE в случае успешного завершения или FALSE в случае возникновения ошибки.

Список изменений

Версия	Описание
7.0.0	В случае, если ob_start() используется внутри callback-функции буфера вывода, эта функция больше не будет приводить к ошибке `E_ERROR`, а вместо этого будет вызывать `E_RECOVERABLE_ERROR`, позволяя сторонним обработчикам ошибок поймать ее.
5.4.0	Третий параметр ob_start() изменен с булева (boolean) параметра `erase` (который при установке в `FALSE` предотвращал удаление буфера до тех пор, пока не завершалась работа скрипта) на целочисленный (integer) параметр `flags`. К сожалению, это означает появление несовместимости API для кода, который использовал третий параметр до версии PHP 5.4.0. Смотрите пример с флагами, чтобы понять как работать с кодом, чтобы он поддерживал совместимость с обеими версиями.
5.4.0	Параметр chunk_size, установленный в 1, теперь приводит к выводу по 1 байту в выходной буфер.
4.3.2	Функция вернет `FALSE` в случае, если `output_callback` не сможет быть выполнена.

Примеры

Пример #1 Пример callback-функции, определенной пользователем


<?php

function callback($buffer)
{
  // заменить все яблоки апельсинами
  return (str_replace("яблоки", "апельсины", $buffer));
}

ob_start("callback");

?>
<html>
<body>
<p>Это все равно что сравнить яблоки и апельсины.</p>
</body>
</html>
<?php

ob_end_flush();

?>

Результат выполнения данного примера:

<html>
<body>
<p>Это все равно что сравнить апельсины и апельсины.</p>
</body>
</html>

Пример #2 Создание нестираемого буфера вывода с совместимостью с версиями PHP 5.3 и 5.4


<?php

if (version_compare(PHP_VERSION, '5.4.0', '>=')) {
  ob_start(null, 0, PHP_OUTPUT_HANDLER_STDFLAGS ^
    PHP_OUTPUT_HANDLER_REMOVABLE);
} else {
  ob_start(null, 0, false);
}

?>

Смотрите также

ob_get_contents() - Возвращает содержимое буфера вывода
ob_end_clean() - Очищает (стирает) буфер вывода и отключает буферизацию вывода
ob_end_flush() - Сброс (отправка) буфера вывода и отключение буферизации вывода
ob_implicit_flush() - Функция включает/выключает неявный сброс
ob_gzhandler() - callback-функция, используемая для gzip-сжатия буфера вывода при вызове ob_start
ob_iconv_handler() - Преобразует символы из текущей кодировки в кодировку выходного буфера
mb_output_handler() - Callback-функция, преобразующая кодировку символов в выходном буфере
ob_tidyhandler() - Функция обратного вызова ob_start для восстановление буфера

Вернуться к: Функции контроля вывода