Funções de Controle de Saída do PHP: Tudo o Que Você Precisa Saber

Normalmente, cada echo, print ou trecho de HTML em um script PHP é enviado ao navegador no momento em que é executado. O buffer de saída permite interceptar essa saída e mantê-la na memória (em um buffer), para que você possa inspecioná-la, editá-la, descartá-la ou enviá-la posteriormente. As funções de controle de saída do PHP são as ferramentas integradas que gerenciam esse buffer.

Este capítulo explica o que é o buffer de saída, por que ele resolve problemas reais e como cada função ob_* funciona — com exemplos executáveis.

Por que o buffer de saída é importante

O buffer de saída vai além de uma simples curiosidade. Ele resolve vários problemas comuns do PHP:

• Evitar erros de "headers already sent". No PHP, você deve chamar header() e setcookie() antes de qualquer saída chegar ao navegador. Ao usar o buffer, você ainda pode enviar cabeçalhos após a execução dos seus templates, pois nada foi enviado ainda. Consulte headers_sent().
• Capturar a saída como string. Renderize um template ou inclua um arquivo e capture o resultado como uma variável em vez de imprimi-lo — a base da maioria dos motores de templates simples.
• Pós-processar a página inteira. Minifique HTML, substitua placeholders ou comprima a saída (gzip) em um único ponto antes de enviá-la.
• Descartar saída indesejada. Elimine ruído de uma biblioteca de terceiros ou uma instrução de depuração que não deve ser exibida ao usuário.

As funções de controle de saída

Aqui estão as funções mais utilizadas. Todas operam no buffer iniciado por ob_start().

Capturar saída como string

O uso mais comum do buffering é capturar o que um bloco de código imprime e armazená-lo em uma variável. ob_get_clean() retorna o buffer e interrompe o buffering em uma única chamada:

Nada chega ao navegador até o echo final, que imprime HELLO, WORLD!. Capturamos o texto, transformamos e só então o enviamos. É exatamente assim que uma pequena função de template funciona:

<?php

function renderTemplate(string $name): string {
    ob_start();
    echo "Hello, $name!";
    return ob_get_clean();   // contents + stop buffering
}

echo renderTemplate("Ada");

Isso imprime Hello, Ada!. Em um projeto real, o bloco em buffer seria um template HTML completo com tags <?= $name ?> incorporadas.

Enviar o buffer ao navegador

Quando você só quer atrasar a saída (sem capturá-la), use ob_end_flush() para enviar tudo de uma vez:

Enquanto o buffer está aberto, você também pode inspecioná-lo com ob_get_length() e ob_get_level():

<?php

ob_start();
echo "buffered text";
echo "\nLevel: " . ob_get_level();   // 1 — one buffer is active
echo "\nLength: " . ob_get_length(); // bytes captured so far
ob_end_flush();

ob_get_level() retorna 1 porque um único buffer está ativo; se você chamar ob_start() novamente dentro dele, o nível passa a ser 2 (os buffers se aninham como uma pilha).

Transformar a saída com um callback

ob_start() aceita um callback que recebe o buffer completo e retorna a versão modificada. É assim que os minificadores de saída e os filtros de busca e substituição funcionam:

<?php

ob_start(function (string $buffer): string {
    return str_replace("cat", "dog", $buffer);
});

echo "I have a cat.";
ob_end_flush();

O callback é executado quando o buffer é liberado, então a página exibe I have a dog.. O mesmo padrão é utilizado pelo ob_gzhandler, o callback integrado do PHP para comprimir a saída com gzip.

Armadilhas comuns

• Sempre feche o que você abrir. Cada ob_start() deve ser correspondido por uma chamada de flush ou clean. Um buffer desbalanceado deixa a saída presa na memória e ela nunca chega ao usuário.
• Os buffers se aninham. Cada ob_start() adiciona um nível. ob_get_clean() fecha apenas o mais interno; use ob_get_level() em um loop se precisar desfazer vários.
• ob_get_contents() não interrompe o buffering — apenas as funções *_clean e *_end_* fazem isso. Confundi-las é uma fonte frequente de saída duplicada.
• Um buffer tem tamanho limitado. Por padrão, o PHP faz flush automaticamente quando o buffer atinge o valor de output_buffering bytes (php.ini), portanto não conte com ele para armazenar uma quantidade ilimitada de dados.

Conclusão

O buffer de saída oferece controle sobre quando e como a saída do seu script é enviada. Use-o para capturar conteúdo renderizado como string, para definir cabeçalhos após gerar uma página, para descartar saída indesejada ou para pós-processar toda a resposta em um único lugar. Assim que você entender o ciclo start/get/clean/flush, a família ob_* é pequena e previsível.

Leitura relacionada: echo e print, PHP header(), PHP Sessions e PHP Cookies.

Prática