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

Quando o PHP executa um script, todo echo, print ou bloco HTML normalmente é enviado ao cliente imediatamente. O buffer de saída muda isso: ele retém tudo que o script imprimiria em um buffer na memória, permitindo que você capture, modifique ou descarte o conteúdo antes que ele saia do servidor. A função ob_start() é a função nativa que ativa esse buffering.

Este capítulo explica o que ob_start() faz, seus parâmetros, como capturar e transformar a saída, os casos de uso mais comuns no mundo real e as armadilhas que costumam pegar as pessoas de surpresa.

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

ob_start() ativa o buffer de saída. Enquanto o buffering está ativo, nada que o script imprime é enviado ao navegador. Em vez disso, tudo se acumula em um buffer interno até que você o envie explicitamente (flush), obtenha como string ou descarte.

A única coisa que o buffering não retém são os cabeçalhos HTTP. Como o corpo não é mais enviado imediatamente, você ainda pode chamar funções como header() depois de já ter ecoado saída — e esse é o motivo mais comum pelo qual os desenvolvedores recorrem a ob_start().

Os buffers também são aninhados: cada chamada a ob_start() empurra um novo buffer para uma pilha, e a função de fechamento/flush correspondente remove o topo. Você pode verificar a profundidade da pilha com ob_get_level().

Sintaxe

ob_start(
    ?callable $callback = null,
    int $chunk_size = 0,
    int $flags = PHP_OUTPUT_HANDLER_STDFLAGS
): bool

Parâmetros:

• $callback — Opcional. Uma função que recebe o conteúdo do buffer (e um bitmask de status) e retorna a string que será realmente enviada. Use-o para transformar tudo que o script imprime — por exemplo, minificar HTML ou compactá-lo com gzip.
• $chunk_size — Opcional. Se maior que 0, o callback é invocado sempre que o buffer atingir esse número de bytes, em vez de apenas quando o buffer for liberado. 0 (o padrão) significa liberar somente na conclusão.
• $flags — Opcional. Um bitmask que controla se o buffer pode ser limpo, liberado e removido. O padrão PHP_OUTPUT_HANDLER_STDFLAGS permite as três operações.

Valor de retorno: true em caso de sucesso, false em caso de falha.

Uso Básico: Capturando a Saída

O padrão mais comum é iniciar um buffer, imprimir algo e depois capturá-lo em uma variável com ob_get_clean() (que retorna o buffer e desativa o buffering em uma única etapa):

<?php

ob_start();                 // start buffering — nothing is sent yet
echo "Hello, ";
echo "world!";
$output = ob_get_clean();   // grab the buffer as a string, stop buffering

echo strtoupper($output);   // now we control what actually gets sent

Saída:

HELLO, WORLD!

Aqui, as duas chamadas echo nunca chegam diretamente ao cliente. ob_get_clean() retorna "Hello, world!", e apenas a versão em maiúsculas é finalmente impressa. Esse fluxo de "capturar e depois transformar" é o que torna o buffering poderoso.

Transformando a Saída com um Callback

Em vez de capturar manualmente, você pode passar um callback para ob_start(). O PHP o executa automaticamente sobre o buffer quando este é liberado (aqui, ao final do script):

<?php

function addBang(string $buffer): string
{
    return str_replace("world", "World!", $buffer);
}

ob_start("addBang");
echo "hello world";
// buffer is flushed automatically at script end → callback runs

Saída:

hello World!

É exatamente assim que handlers nativos como ob_gzhandler() funcionam — passe-o como callback e sua página inteira será compactada com gzip de forma transparente.

Casos de Uso Comuns

• Enviar cabeçalhos após a saída. Como o corpo está em buffer, você ainda pode chamar header() ou setcookie() após ecoar HTML, evitando o temido aviso "headers already sent". Consulte headers_sent().
• Templating. Captura o HTML renderizado de um arquivo de template em uma string em vez de imprimi-lo diretamente, para que possa ser retornado, armazenado em cache ou encapsulado em um layout.
• Pós-processamento da página inteira. Minifique HTML, reescreva URLs ou remova comentários via callback antes que qualquer conteúdo seja enviado.
• Compressão. Use ob_gzhandler para comprimir respostas sem alterar as chamadas echo do seu script.

Funções Relacionadas

Raramente você usará ob_start() sozinha. Estas funções gerenciam o buffer que ela cria:

• ob_get_contents() — Retorna o conteúdo do buffer sem limpá-lo.
• ob_get_clean() — Retorna o buffer e desativa o buffering.
• ob_clean() — Descarta o conteúdo do buffer, mas mantém o buffering ativo.
• ob_end_flush() — Envia o buffer ao cliente e desativa o buffering.
• ob_end_clean() — Descarta o buffer e desativa o buffering (não envia nada).
• ob_get_level() — Retorna quantos buffers aninhados estão ativos no momento.

Para uma visão geral mais ampla, consulte PHP Output Control.

Armadilhas Comuns

• Sempre feche o que você abre. Cada ob_start() deve ter uma chamada correspondente de flush/clean. Um buffer não fechado é liberado automaticamente ao final do script, mas deixá-los abertos em scripts longos pode ocultar saída ou desperdiçar memória.
• ob_get_clean() retorna false se nenhum buffer estiver ativo. Chamá-lo sem um ob_start() correspondente retorna false, não uma string vazia.
• Buffering ≠ cabeçalhos infinitos. Os cabeçalhos em si não são armazenados em buffer; apenas o corpo é. Uma vez que qualquer buffer seja liberado para o cliente, os cabeçalhos ficam bloqueados.

Conclusão

ob_start() ativa o buffer de saída para que o PHP mantenha a saída do script na memória em vez de enviá-la imediatamente. Isso permite capturar a saída em uma string, transformá-la com um callback, enviar cabeçalhos após imprimir ou comprimir uma página inteira. Combine-a com ob_get_clean() para capturar, ob_end_flush() para enviar e ob_end_clean() para descartar — e lembre-se sempre de fechar cada buffer que você abrir.

Prática