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

Описание

ob_start ( callable $callback = null , int $chunk_size = 0 , int $flags = PHP_OUTPUT_HANDLER_STDFLAGS ) : bool

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

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

Внимание

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

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

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

callback

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

handler ( string $buffer , int $phase = ? ) : string

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

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

Параметр 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-функции.

Замечание:
Функция ob_gzhandler() была введена для облегчения отправки gz-кодированных данных браузерам, поддерживающим сжатые веб-страницы. 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 как сокращение этой комбинации.

Каждый флаг управляет доступом к набору функций, как описано ниже:

Константа	Функции
`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 в случае возникновения ошибки.

Примеры

Пример #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 для восстановление буфера