Função PHP ob_get_contents(): Tudo o que Você Precisa Saber

Normalmente, quando seu script usa echo ou print, o PHP envia a saída diretamente para o navegador. O buffer de saída permite interceptar essa saída e mantê-la na memória, para que você possa capturá-la, modificá-la ou descartá-la antes que chegue ao cliente. A função ob_get_contents() é a ferramenta que permite ler o que está atualmente nesse buffer.

Este capítulo explica o que ob_get_contents() retorna, quando usá-la, os pontos de atenção e como ela se encaixa junto com as outras funções de controle de saída.

O que ob_get_contents() faz

ob_get_contents() retorna o conteúdo do buffer de saída ativo sem limpá-lo nem encerrar o buffering. O buffer continua coletando a saída, então você pode chamar a função várias vezes para verificar o que foi acumulado até o momento.

Ela só funciona enquanto um buffer iniciado por ob_start() estiver ativo. Se não houver buffer ativo, ela retorna false.

Sintaxe

ob_get_contents(): string|false

• Parâmetros: nenhum.
• Valor de retorno: o conteúdo atual do buffer como string, ou false se o buffer de saída não estiver ativo.

Um exemplo básico

<?php

ob_start();                       // 1. Start capturing output
echo "This will be buffered";     // 2. Goes into the buffer, not the screen
$output = ob_get_contents();      // 3. Read the buffer into a variable
ob_end_clean();                   // 4. Discard the buffer and stop buffering

echo "Captured: " . $output;

Isso imprime:

Captured: This will be buffered

Aqui ob_start() inicia o buffering, então o echo é mantido na memória em vez de ser enviado ao navegador. ob_get_contents() copia esse texto para $output. Por fim, ob_end_clean() descarta o buffer e desativa o buffering — sem ele, o texto armazenado ainda seria enviado para a página.

ob_get_contents() não esvazia o buffer

Um ponto de confusão comum: ler o buffer não o altera. A saída ainda está lá e será enviada ao navegador quando o buffering terminar (a menos que você a limpe).

<?php

ob_start();
echo "Hello";
$first = ob_get_contents();   // "Hello"
echo " World";
$second = ob_get_contents();  // "Hello World" — the buffer kept growing
ob_end_flush();               // sends "Hello World" to the browser

var_dump($first, $second);

Isso produz:

Hello World
string(5) "Hello"
string(11) "Hello World"

Se em vez disso você quiser ler e apagar o buffer em um único passo, use ob_get_clean().

Quando devo usar isso?

• Capturando saída renderizada. Renderize um template ou inclua um arquivo e obtenha o resultado como string em vez de imprimi-lo — útil para e-mails, cache ou geração de arquivos.
• Pós-processamento de HTML. Faça buffer de uma página, leia-a com ob_get_contents(), aplique uma transformação (minificação, substituição de placeholders) e depois envie o resultado.
• Suprimindo ou inspecionando a saída de uma função ou biblioteca que imprime diretamente.

<?php

function renderGreeting(string $name): void
{
    echo "<p>Hello, {$name}!</p>";
}

ob_start();
renderGreeting("Ada");
$html = ob_get_contents();   // capture instead of printing
ob_end_clean();

$html = str_replace("Hello", "Welcome", $html);
echo $html;

Isso produz:

<p>Welcome, Ada!</p>

Pontos de atenção

• Retorna false, não uma string vazia, quando nenhum buffer está ativo. Use uma verificação estrita (=== false) se precisar distinguir "sem buffer" de "buffer vazio".
• Buffers aninhados: ob_get_contents() lê apenas o nível de buffer mais interno (atual). Para ver quantos buffers estão empilhados, use ob_get_level().
• Não encerra o buffering. Use-a junto com ob_end_clean() ou ob_end_flush() quando terminar.

Funções relacionadas

• ob_start() — ativa o buffer de saída.
• ob_get_clean() — obtém o conteúdo do buffer e o descarta.
• ob_get_length() — obtém o tamanho do buffer em bytes.
• Visão geral do controle de saída PHP — toda a família de funções ob_*.

Conclusão

ob_get_contents() lê o buffer de saída atual como string sem limpá-lo nem encerrar o buffering. É o bloco de construção para capturar saída renderizada, pós-processar HTML e suprimir saída direta. Lembre-se de que ela retorna false quando nenhum buffer está ativo e que deixa o buffer intacto — use ob_get_clean() quando quiser ler e limpar em um único movimento.

Prática