(PHP 4, PHP 5, PHP 7)
ob_start — Включение буферизации вывода
$output_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-функций, вывод последовательно фильтруется для каждой из них в порядке вложения.
output_callback
Можно задать необязательный параметр output_callback.
Эта функция принимает строку в виде аргумента и должна также вернуть строку.
Она вызывается при сбросе (отправке) или очистке (с помощью
ob_flush(), ob_clean() или подобных функций)
или если буфер вывода сбрасывается в браузер по окончанию запроса.
При вызове функции output_callback, она получает
содержимое буфера и, как ожидается, должна вернуть обновленное содержимое для буфера вывода,
которое будет отправлено браузеру.
Если output_callback не является допустимой функцией, то
эта функция вернет FALSE.
Описание функции для этого параметра:
$buffer
[, int $phase
] ) : stringbufferphasePHP_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-функции.
Замечание:
Функция 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 в случае возникновения ошибки.
| Версия | Описание |
|---|---|
| 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 байту в выходной буфер. |
Пример #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);
}
?>