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

Когда PHP работает с буферизацией вывода, всё, что выводит ваш скрипт с помощью echo, собирается в буфер в памяти вместо того, чтобы немедленно отправляться в браузер. Иногда нужно выбросить захваченный вывод и полностью остановить буферизацию — например, после захвата данных только для их изучения или когда ошибка означает, что наполовину сформированный ответ не должен дойти до пользователя. Именно это делает ob_end_clean(). На этой странице рассматриваются его синтаксис, возвращаемое значение, типичные сценарии использования и отличия от связанных функций ob_*.

Что такое функция ob_end_clean()?

ob_end_clean() выполняет два действия за один вызов для самого верхнего (самого последнего запущенного) буфера вывода:

1. Удаляет его текущее содержимое — буферизованный вывод стирается, а не отправляется.
2. Отключает этот уровень буферизации — буфер закрывается и удаляется из стека.

Функция существует начиная с PHP 4. Название расшифровывается как output buffer (ob) — end — clean: «end» означает закрытие уровня буфера, «clean» — выброс содержимого (в отличие от «flush», которое отправляет его).

Синтаксис

ob_end_clean(): bool

Функция не принимает аргументов и возвращает boolean.

Возвращаемое значение и обработка ошибок

Поскольку функция выдаёт предупреждение, когда буфер не активен, защитите вызов с помощью ob_get_level(), если вы не уверены, что буфер открыт:

<?php
if (ob_get_level() > 0) {
    ob_end_clean();
}
?>

Базовый пример

<?php
ob_start();                 // Start buffering
echo "This will be thrown away";
ob_end_clean();             // Discard the buffer, stop buffering

echo "Only this line reaches the browser";
?>

Вывод:

Only this line reaches the browser

Первый echo так и не появится: ob_end_clean() удалил буфер, содержавший "This will be thrown away".

Когда использовать эту функцию?

• Подавление нежелательного вывода из функции, библиотеки или шаблона, которые вы не контролируете, чтобы они не могли испортить ответ.
• Отмена наполовину сформированной страницы, когда в середине обработки происходит ошибка или редирект, чтобы пользователь получил чистый ответ вместо сломанного.
• Захват и удаление вывода во время тестирования или измерений (например, для замера времени отрисовки без реальной отправки данных).

<?php
ob_start();
try {
    render_complex_page();          // emits lots of output
    throw new RuntimeException('boom');
} catch (Throwable $e) {
    ob_end_clean();                 // drop the partial page
    http_response_code(500);
    echo "Sorry, something went wrong.";
}
?>

ob_end_clean() и связанные функции

Семейство функций ob_* делится по двум осям — clean vs. flush (удалить vs. отправить) и end vs. get (закрыть буфер vs. оставить открытым / вернуть строку):

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

Вложенные буферы

Буферы вывода образуют стек. ob_end_clean() влияет только на самый внутренний буфер; внешние буферы остаются нетронутыми. Каждый уровень требует отдельного вызова для закрытия:

<?php
ob_start();           // level 1
echo "outer ";
ob_start();           // level 2
echo "inner";
ob_end_clean();       // drops "inner", level 1 still open
echo " world";
ob_end_flush();       // sends "outer  world"
?>

Вывод:

outer  world

Заключение

ob_end_clean() удаляет содержимое активного буфера вывода и закрывает этот уровень буферизации, возвращая true при успехе. Используйте её, чтобы отбросить вывод, который вы никогда не хотите отправлять — а для получения содержимого, его отправки или продолжения буферизации обращайтесь к ob_get_clean(), ob_end_flush() или ob_clean(). Полную картину смотрите в обзоре управления выводом PHP.

Практика