ob_start

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_startВключает буферизацию вывода

Описание

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

Функция включает буферизацию вывода. Пока буферизация вывода активна, вывод из скрипта не отправляется, вместо этого вывод сохраняется во внутреннем буфере. Раздел «Какой вывод буферизуется?» рассказывает, на какой именно вывод это влияет.

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

Подробное описание буферов вывода даёт раздел «Пользовательские буферы вывода».

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

callback

Параметр callback принимает необязательный аргумент с типом callable. Когда требуется, чтобы при вызове с аргументами функция не вызывала callback-функцию, в параметр передают значение null.

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

Сигнатура callback-функции:

handler(string $buffer, int $phase = ?): string
buffer
Содержимое буфера вывода.
phase
Битовая маска из семейства констант PHP_OUTPUT_HANDLER_* . Подробнее о флагах рассказывает раздел «Флаги, передаваемые обработчикам вывода».

Если параметр callback вернёт false, возвращается содержимое буфера. Подробнее об этом рассказывает раздел «Значения, которые возвращает обработчик вывода».

Внимание

Вызов любой из следующих функций из обработчика вывода выдаст фатальную ошибку: ob_clean(), ob_end_clean(), ob_end_flush(), ob_flush(), ob_get_clean(), ob_get_flush(), ob_start().

Подробнее о callback-функциях (обработчиках вывода) рассказывают разделы «Обработчики вывода» и «Работа с обработчиками вывода».

chunk_size

Буфер будет сбрасываться после каждого блока кода, размер буфера которого достиг или превысил значение параметра chunk_size, если передали необязательный параметр chunk_size. Значение по умолчанию 0 означает, что вывод буферизуется до тех пор, пока буфер не выключится. Подробнее об этом рассказывает раздел «Размер буфера».

flags

Параметр flags — битовая маска, которая управляет операциями с буфером вывода. По умолчанию разрешаются очистка, сброс и удаление буферов вывода, что явно устанавливается флагами управления буфером . Подробнее об этом рассказывает раздел «Операции, разрешённые для буферов».

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

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

Замечание: До PHP 8.4.0 через параметр flags также устанавливали флаги статуса обработчика вывода.

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

Функция возвращает 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

ob_start
(null, 0, PHP_OUTPUT_HANDLER_STDFLAGS ^ PHP_OUTPUT_HANDLER_REMOVABLE);

?>

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

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

Добавить

Примечания пользователей 6 notes

up
53
Ray Paseur (Paseur ... ImagineDB.com)
19 years ago
You can use PHP to generate a static HTML page. Useful if you have a complex script that, for performance reasons, you do not want site visitors to run repeatedly on demand. A "cron" job can execute the PHP script to create the HTML page. For example:

<?php // CREATE index.html
ob_start();
/* PERFORM COMLEX QUERY, ECHO RESULTS, ETC. */
$page = ob_get_contents();
ob_end_clean();
$cwd = getcwd();
$file = "$cwd" .'/'. "index.html";
@
chmod($file,0755);
$fw = fopen($file, "w");
fputs($fw,$page, strlen($page));
fclose($fw);
die();
?>
up
20
net_navard at yahoo dot com
18 years ago
Hello firends

ob_start() opens a buffer in which all output is stored. So every time you do an echo, the output of that is added to the buffer. When the script finishes running, or you call ob_flush(), that stored output is sent to the browser (and gzipped first if you use ob_gzhandler, which means it downloads faster).

The most common reason to use ob_start is as a way to collect data that would otherwise be sent to the browser.

These are two usages of ob_start():

1-Well, you have more control over the output. Trivial example: say you want to show the user an error message, but the script has already sent some HTML to the browser. It'll look ugly, with a half-rendered page and then an error message. Using the output buffering functions, you can simply delete the buffer and sebuffer and send only the error message, which means it looks all nice and neat buffer and send
2-The reason output buffering was invented was to create a seamless transfer, from: php engine -> apache -> operating system -> web user

If you make sure each of those use the same buffer size, the system will use less writes, use less system resources and be able to handle more traffic.

With Regards, Hossein
up
28
ed.oohay (a) suamhcs_rodnan
21 years ago
Output Buffering even works in nested scopes or might be applied in recursive structures... thought this might save someone a little time guessing and testing :)

<pre><?php

ob_start
(); // start output buffer 1
echo "a"; // fill ob1

ob_start(); // start output buffer 2
echo "b"; // fill ob2
$s1 = ob_get_contents(); // read ob2 ("b")
ob_end_flush(); // flush ob2 to ob1

echo "c"; // continue filling ob1
$s2 = ob_get_contents(); // read ob1 ("a" . "b" . "c")
ob_end_flush(); // flush ob1 to browser

// echoes "b" followed by "abc", as supposed to:
echo "<HR>$s1<HR>$s2<HR>";

?></pre>

... at least works on Apache 1.3.28

Nandor =)
up
6
Asher Haig (ahaig at ridiculouspower dot com)
17 years ago
When a script ends, all buffered output is flushed (this is not a bug: http://bugs.php.net/bug.php?id=42334&thanks=4). What happens when the script throws an error (and thus ends) in the middle of an output buffer? The script spits out everything in the buffer before printing the error!

Here is the simplest solution I have been able to find. Put it at the beginning of the error handling function to clear all buffered data and print only the error:

$handlers = ob_list_handlers();
while ( ! empty($handlers) ) {
ob_end_clean();
$handlers = ob_list_handlers();
}
up
7
Chris
14 years ago
Careful with while using functions that change headers of a page; that change will not be undone when ending output buffering.

If you for instance have a class that generates an image and sets the appropriate headers, they will still be in place after the end of ob.

For instance:
<?php
ob_start
();
myClass::renderPng(); //header("Content-Type: image/png"); in here
$pngString = ob_get_contents();
ob_end_clean();
?>

will put the image bytes into $pngString, and set the content type to image/png. Though the image will not be sent to the client, the png header is still in place; if you do html output here, the browser will most likely display "image error, cannot be viewed", at least firefox does.

You need to set the correct image type (text/html) manually in this case.
up
3
ernest at vogelsinger dot at
19 years ago
When you rely on URL rewriting to pass the PHP session ID you should be careful with ob_get_contents(), as this might disable URL rewriting completely.

Example:
ob_start();
session_start();
echo '<a href=".">self link</a>';
$data = ob_get_contents();
ob_end_clean();
echo $data;

In the example above, URL rewriting will never occur. In fact, rewriting would occur if you ended the buffering envelope using ob_end_flush(). It seems to me that rewriting occurs in the very same buffering envelope where the session gets started, not at the final output stage.

If you need a scenario like the one above, using an "inner envelope" will help:

ob_start();
ob_start(); // add the inner buffering envelope
session_start();
echo '<a href=".">self link</a>';
ob_end_flush(); // closing the inner envelope will activate URL rewriting
$data = ob_get_contents();
ob_end_clean();
echo $data;

In case you're interested or believe like me that this is rather a design flaw instead of a feature, please visit bug #35933 (http://bugs.php.net/bug.php?id=35933) and comment on it.
To Top