Função ob_clean() do PHP: Tudo o Que Você Precisa Saber

A função PHP ob_clean() descarta tudo o que foi escrito no buffer de saída atual sem desativar o buffering. É a função ideal quando seu script já produziu alguma saída, mas você decidiu que essa saída está errada (um var_dump de depuração esquecido, um template renderizado pela metade, uma mensagem de erro) e quer descartá-la para continuar gerando conteúdo novo.

Esta página explica o que ob_clean() faz, sua assinatura e valor de retorno, as armadilhas mais comuns (especialmente a diferença em relação a ob_end_clean()) e padrões práticos de uso.

O que é output buffering

Normalmente o PHP envia a saída ao cliente no momento em que você usa echo. O output buffering muda esse comportamento: após chamar ob_start(), tudo o que você imprime é capturado em um buffer na memória em vez de ser enviado imediatamente. Nada sai do PHP até que você descarregue o buffer ou o script termine.

Esse atraso é o que torna o buffering útil — enquanto a saída está no buffer você ainda pode:

• enviar ou modificar cabeçalhos HTTP (header(), setcookie()) mesmo após imprimir,
• inspecionar, reescrever ou descartar a saída capturada,
• compactar a resposta inteira antes de enviá-la.

ob_clean() é a operação de "descarte" nessa lista.

Sintaxe

ob_clean(): bool

• Parâmetros: nenhum.
• Valor de retorno: true em caso de sucesso, false em caso de falha. Ela falha (e emite um aviso/warning) quando não há buffer de saída ativo para limpar.

Um exemplo 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

Saída:

Only this line is shown.

O primeiro echo foi para o buffer, ob_clean() o esvaziou, e apenas o segundo echo sobreviveu. Note que o buffering ainda está ativo após ob_clean() — é por isso que o ob_end_flush() final é necessário para realmente emitir a segunda linha.

Um caso de uso real: descartando uma renderização com falha

ob_clean() brilha quando você gera saída de forma otimista e então encontra uma condição que a 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']);

Saída:

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

Aqui ob_get_clean() retorna o conteúdo do buffer e encerra o buffering em um único passo, enquanto ob_clean() é usado no meio da renderização para abandonar o markup parcialmente construído.

ob_clean() vs as funções relacionadas

A família de controle de saída tem quatro nomes de aparência similar. Os dois eixos são você mantém os dados? e você mantém o buffer?

Por isso o erro mais comum é usar ob_end_clean() quando se pretendia usar ob_clean(): a primeira fecha o nível do buffer, então um echo posterior não é mais armazenado em buffer e qualquer chamada ob_* subsequente pode alertar que nenhum buffer está ativo.

Armadilhas

• O buffering deve estar ativo. Chamar ob_clean() sem um ob_start() em vigor retorna false e gera um aviso. Use ob_get_level() como proteção se não tiver certeza: if (ob_get_level() > 0) { ob_clean(); }.
• Ela só limpa o buffer do topo. Os buffers se aninham. ob_clean() afeta o buffer mais interno (iniciado mais recentemente), não todos eles.
• Ela não redefine os cabeçalhos. ob_clean() esvazia apenas o texto de saída; os cabeçalhos que você já enfileirou com header() não são afetados.

Conclusão

ob_clean() descarta o conteúdo do buffer de saída atual mantendo o buffering ativo, tornando-a a ferramenta certa para abandonar saídas que você decidiu não enviar e continuar a partir de um estado limpo. Lembre-se da distinção em relação a ob_end_clean() (que também fecha o buffer) e a ob_get_clean() (que devolve o conteúdo para você). Para uma visão geral de toda a família, veja PHP Output Control.

Prática