Функция PHP ob_get_contents(): всё, что нужно знать

Обычно, когда скрипт выполняет echo или print, PHP немедленно отправляет данные в браузер. Буферизация вывода позволяет перехватить этот вывод и удержать его в памяти, чтобы вы могли захватить, изменить или отбросить его до отправки клиенту. Функция ob_get_contents() — это инструмент, который позволяет прочитать содержимое, находящееся в буфере в данный момент.

В этой главе объясняется, что возвращает ob_get_contents(), когда её следует использовать, на что обратить внимание и как она взаимодействует с другими функциями управления выводом.

Что делает ob_get_contents()

ob_get_contents() возвращает содержимое активного буфера вывода без его очистки и без остановки буферизации. Буфер продолжает накапливать вывод, поэтому функцию можно вызывать несколько раз, чтобы посмотреть, что накопилось к текущему моменту.

Функция работает только при наличии активного буфера, запущенного ob_start(). Если активного буфера нет, она возвращает false.

Синтаксис

ob_get_contents(): string|false

• Параметры: отсутствуют.
• Возвращаемое значение: текущее содержимое буфера в виде строки или false, если буферизация вывода не активна.

Простой пример

<?php

ob_start();                       // 1. Start capturing output
echo "This will be buffered";     // 2. Goes into the buffer, not the screen
$output = ob_get_contents();      // 3. Read the buffer into a variable
ob_end_clean();                   // 4. Discard the buffer and stop buffering

echo "Captured: " . $output;

Вывод:

Captured: This will be buffered

Здесь ob_start() начинает буферизацию, поэтому echo сохраняется в памяти, а не отправляется в браузер. ob_get_contents() копирует этот текст в переменную $output. Наконец, ob_end_clean() удаляет буфер и отключает буферизацию — без этого вызова содержимое буфера всё равно было бы отправлено на страницу.

ob_get_contents() не очищает буфер

Распространённое заблуждение: чтение буфера не затрагивает его содержимое. Данные остаются в буфере и будут отправлены в браузер по завершении буферизации (если их явно не очистить).

<?php

ob_start();
echo "Hello";
$first = ob_get_contents();   // "Hello"
echo " World";
$second = ob_get_contents();  // "Hello World" — the buffer kept growing
ob_end_flush();               // sends "Hello World" to the browser

var_dump($first, $second);

Вывод:

Hello World
string(5) "Hello"
string(11) "Hello World"

Если вы хотите прочитать и очистить буфер за один шаг, используйте ob_get_clean().

Когда это используется?

• Захват отрисованного вывода. Отрисуйте шаблон или подключите файл, а затем получите результат в виде строки вместо вывода на экран — удобно для электронных писем, кэширования или генерации файлов.
• Постобработка HTML. Буферизуйте страницу, прочитайте её с помощью ob_get_contents(), выполните преобразование (минификация, замена плейсхолдеров), затем выведите результат.
• Подавление или инспекция вывода функции или библиотеки, которая выводит данные напрямую.

<?php

function renderGreeting(string $name): void
{
    echo "<p>Hello, {$name}!</p>";
}

ob_start();
renderGreeting("Ada");
$html = ob_get_contents();   // capture instead of printing
ob_end_clean();

$html = str_replace("Hello", "Welcome", $html);
echo $html;

Вывод:

<p>Welcome, Ada!</p>

Подводные камни

• Возвращает false, а не пустую строку, если буфер не активен. Используйте строгую проверку (=== false), если нужно различить «нет буфера» и «пустой буфер».
• Вложенные буферы: ob_get_contents() читает только самый внутренний (текущий) уровень буфера. Чтобы узнать, сколько буферов вложено, используйте ob_get_level().
• Функция не останавливает буферизацию. Сочетайте её с ob_end_clean() или ob_end_flush() по завершении работы.

Связанные функции

• ob_start() — включить буферизацию вывода.
• ob_get_clean() — получить содержимое буфера и очистить его.
• ob_get_length() — получить длину буфера в байтах.
• Обзор управления выводом в PHP — полное семейство функций ob_*.

Заключение

ob_get_contents() читает текущий буфер вывода в виде строки, не очищая его и не завершая буферизацию. Это базовый инструмент для захвата отрисованного вывода, постобработки HTML и подавления прямого вывода. Помните, что функция возвращает false при отсутствии активного буфера и оставляет буфер нетронутым — используйте ob_get_clean(), когда нужно прочитать и очистить за один вызов.

Практика