Función PHP ob_clean(): Todo lo que necesitas saber

La función PHP ob_clean() descarta todo lo escrito en el búfer de salida actual sin desactivar el almacenamiento en búfer. Es la función a la que se recurre cuando el script ya ha producido alguna salida, pero se ha decidido que esa salida es incorrecta (un var_dump de depuración residual, una plantilla a medio renderizar, un mensaje de error) y se desea descartarla para continuar generando contenido nuevo.

Esta página explica qué hace ob_clean(), su firma y valor de retorno, los problemas que suelen surgir (especialmente la diferencia con ob_end_clean()) y patrones prácticos para usarla.

Qué es el almacenamiento en búfer de salida

Normalmente PHP envía la salida al cliente en el momento en que se ejecuta echo. El almacenamiento en búfer de salida cambia ese comportamiento: después de llamar a ob_start(), todo lo que se imprime se captura en un búfer en memoria en lugar de enviarse inmediatamente. Nada sale de PHP hasta que se vacía el búfer o finaliza el script.

Ese retraso es lo que hace útil el almacenamiento en búfer — mientras la salida permanece en el búfer todavía es posible:

• enviar o modificar cabeceras HTTP (header(), setcookie()) incluso después de imprimir,
• inspeccionar, reescribir o descartar la salida capturada,
• comprimir toda la respuesta antes de enviarla.

ob_clean() es la operación de "descartar" de esa lista.

Sintaxis

ob_clean(): bool

• Parámetros: ninguno.
• Valor de retorno: true en caso de éxito, false en caso de fallo. Falla (y emite un aviso/advertencia) cuando no hay ningún búfer de salida activo que limpiar.

Un ejemplo básico

<?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

Salida:

Only this line is shown.

El primer echo fue al búfer, ob_clean() lo vació y solo sobrevivió el segundo echo. Nótese que el almacenamiento en búfer sigue activo tras ob_clean() — por eso se necesita el ob_end_flush() final para emitir realmente la segunda línea.

Un caso de uso real: descartar un renderizado fallido

ob_clean() brilla cuando se genera salida de forma optimista y luego se encuentra una condición que la invalida:

<?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']);

Salida:

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

Aquí ob_get_clean() devuelve el contenido del búfer y finaliza el almacenamiento en búfer en un solo paso, mientras que ob_clean() se usa en mitad del renderizado para abandonar el marcado parcialmente construido.

ob_clean() frente a las funciones relacionadas

La familia de control de salida tiene cuatro nombres de aspecto similar. Los dos ejes son ¿se conservan los datos? y ¿se mantiene el búfer?

El error más común es usar ob_end_clean() cuando se quería usar ob_clean(): la primera cierra el nivel del búfer, por lo que un echo posterior ya no se almacena en búfer y cualquier llamada ob_* subsiguiente puede advertir que no hay ningún búfer activo.

Problemas frecuentes

• El almacenamiento en búfer debe estar activo. Llamar a ob_clean() sin un ob_start() en efecto devuelve false y genera un aviso. Comprueba con ob_get_level() si no estás seguro: if (ob_get_level() > 0) { ob_clean(); }.
• Solo limpia el búfer superior. Los búferes se anidan. ob_clean() afecta al búfer más interno (el iniciado más recientemente), no a todos.
• No restablece las cabeceras. ob_clean() solo vacía el texto de salida; las cabeceras que ya hayas encolado con header() no se ven afectadas.

Conclusión

ob_clean() descarta el contenido del búfer de salida actual manteniendo el almacenamiento en búfer activo, lo que la convierte en la herramienta adecuada para abandonar una salida que se ha decidido no enviar y continuar desde un estado limpio. Recuerda la diferencia con ob_end_clean() (que también cierra el búfer) y con ob_get_clean() (que te devuelve el contenido). Para una visión general de toda la familia, consulta PHP Output Control.

Práctica