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

Функция PHP ob_clean() удаляет всё, что было записано в текущий буфер вывода, не отключая буферизацию. Она нужна, когда скрипт уже что-то вывел, но вы решили, что этот вывод неверен (оставшийся отладочный var_dump, частично отрендеренный шаблон, сообщение об ошибке) и хотите выбросить его, продолжив генерировать новый контент.

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

Что такое буферизация вывода

По умолчанию PHP отправляет вывод клиенту в момент вызова echo. Буферизация вывода меняет это поведение: после вызова ob_start() всё, что вы выводите, захватывается в буфер в памяти, а не отправляется немедленно. Ничего не покидает PHP до тех пор, пока вы не сбросите буфер или скрипт не завершится.

Именно эта задержка делает буферизацию полезной — пока вывод находится в буфере, вы всё ещё можете:

• отправлять или изменять HTTP-заголовки (header(), setcookie()) даже после вывода данных,
• просматривать, переписывать или удалять захваченный вывод,
• сжимать весь ответ перед отправкой.

ob_clean() — это операция «удаления» из этого списка.

Синтаксис

ob_clean(): bool

• Параметры: отсутствуют.
• Возвращаемое значение: true при успехе, false при ошибке. Функция завершается с ошибкой (и вызывает уведомление/предупреждение), если нет активного буфера вывода для очистки.

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

<?php
ob_start();                       // start buffering

echo "This text is buffered.\n";
ob_clean();                       // throw the buffered text away

echo "Only this line is shown.\n";

ob_end_flush();                   // send remaining buffer to output

Вывод:

Only this line is shown.

Первый echo попал в буфер, ob_clean() очистил его, и только второй echo остался. Обратите внимание, что буферизация по-прежнему включена после ob_clean() — именно поэтому в конце нужен ob_end_flush(), чтобы фактически отправить вторую строку.

Реальный пример использования: отбрасывание сломанного рендера

ob_clean() особенно полезна, когда вы генерируете вывод оптимистично, а затем сталкиваетесь с условием, которое делает его недействительным:

<?php
function renderUser(?array $user): string
{
    ob_start();

    echo "<div class='card'>";
    echo "  <h2>" . ($user['name'] ?? '') . "</h2>";

    if (empty($user)) {
        ob_clean();                       // scrap the half-built card
        echo "<p>User not found.</p>";    // start fresh
        return ob_get_clean();
    }

    echo "</div>";
    return ob_get_clean();
}

echo renderUser(null);            // <p>User not found.</p>
echo "\n";
echo renderUser(['name' => 'Ann']);

Вывод:

<p>User not found.</p>
<div class='card'>  <h2>Ann</h2></div>

Здесь ob_get_clean() возвращает содержимое буфера и завершает буферизацию в одном шаге, тогда как ob_clean() используется в середине рендера, чтобы отбросить частично построенную разметку.

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

Семейство управления выводом имеет четыре похожих по названию функции. Два критерия: возвращают ли данные? и сохраняют ли буфер открытым?

Типичная ошибка — использование ob_end_clean() вместо ob_clean(): первая закрывает уровень буфера, поэтому последующий echo больше не буферизуется, а любой последующий вызов ob_* может предупредить, что нет активного буфера.

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

• Буферизация должна быть активной. Вызов ob_clean() без активного ob_start() возвращает false и вызывает уведомление. Используйте проверку через ob_get_level(), если не уверены: if (ob_get_level() > 0) { ob_clean(); }.
• Очищается только верхний буфер. Буферы могут быть вложенными. ob_clean() влияет только на самый внутренний (последний запущенный) буфер, но не на все.
• Заголовки не сбрасываются. ob_clean() очищает только текстовый вывод; заголовки, уже поставленные в очередь через header(), остаются неизменными.

Заключение

ob_clean() удаляет содержимое текущего буфера вывода, оставляя буферизацию включённой, что делает её правильным инструментом для отбрасывания вывода, который вы решили не отправлять, с возможностью продолжить с чистого листа. Помните об отличии от ob_end_clean() (которая также закрывает буфер) и от ob_get_clean() (которая возвращает содержимое вам). Обзор всего семейства функций см. в разделе PHP Output Control.

Практика