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

Quando o PHP executa com buffer de saída, tudo o que o seu script echoa é coletado em um buffer na memória em vez de ser enviado diretamente ao navegador. Às vezes você quer descartar essa saída capturada e parar o buffer completamente — por exemplo, após capturar algo apenas para inspecioná-lo, ou quando um erro significa que a resposta parcialmente construída nunca deve chegar ao usuário. É exatamente isso que ob_end_clean() faz. Esta página aborda sua sintaxe, valor de retorno, casos de uso comuns e como ela difere das funções ob_* relacionadas.

O que é a Função ob_end_clean()?

ob_end_clean() faz duas coisas em uma única chamada ao buffer de saída mais externo (iniciado mais recentemente):

1. Descarta seu conteúdo atual — a saída em buffer é deletada, não enviada.
2. Desativa esse nível de buffer — o buffer é fechado e removido da pilha.

A função existe desde o PHP 4. O nome se traduz como output buffer (ob) — end — clean: "end" significa fechar o nível do buffer, "clean" significa descartar o conteúdo (ao contrário de "flush", que o envia).

Sintaxe

ob_end_clean(): bool

Não recebe argumentos e retorna um boolean.

Valor de Retorno e Tratamento de Erros

Como emite um aviso quando nenhum buffer está ativo, proteja a chamada com ob_get_level() quando não tiver certeza se há um buffer aberto:

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

Exemplo Básico

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

Saída:

Only this line reaches the browser

O primeiro echo nunca aparece: ob_end_clean() deletou o buffer que continha "This will be thrown away".

Quando Usar?

• Suprimir saída indesejada de uma função, biblioteca ou template que você não controla, para que não corrompa a resposta.
• Descartar uma página parcialmente renderizada quando ocorre um erro ou redirecionamento no meio do processo, para que o usuário receba uma resposta limpa em vez de uma quebrada.
• Capturar e depois descartar a saída durante testes ou medições (por exemplo, medir quanto tempo leva uma renderização sem realmente imprimi-la).

<?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() vs. Funções Relacionadas

A família ob_* se divide em dois eixos — clean vs. flush (descartar vs. enviar) e end vs. get (fechar o buffer vs. mantê-lo aberto / retornar uma string):

Se precisar do texto descartado como uma string, use ob_get_clean() em vez de ob_end_clean(). Para enviar o buffer em vez de descartá-lo, use ob_end_flush(). Todas essas funções exigem um buffer previamente aberto com ob_start().

Buffers Aninhados

Os buffers de saída formam uma pilha. ob_end_clean() afeta apenas o buffer mais interno; os buffers externos permanecem intactos. Cada nível precisa de sua própria chamada para ser fechado:

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

Saída:

outer  world

Conclusão

ob_end_clean() descarta o conteúdo do buffer de saída ativo e fecha esse nível de buffer, retornando true em caso de sucesso. Use-a para descartar saídas que nunca devem ser enviadas — e recorra a ob_get_clean(), ob_end_flush() ou ob_clean() quando precisar do conteúdo, quiser enviá-lo ou quiser manter o buffer ativo. Consulte a visão geral do controle de output do PHP para uma visão completa.

Prática