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

Quando o PHP captura a saída em um buffer em vez de enviá-la diretamente ao navegador, você eventualmente precisa liberar esse buffer. A função ob_end_flush() faz exatamente isso: ela envia o conteúdo do buffer de saída mais interno para o próximo nível (o navegador ou um buffer externo) e depois exclui esse buffer. Esta página explica o que a função faz, quando usá-la, como ela difere de suas funções relacionadas e os problemas comuns que as pessoas enfrentam.

O Que a Função ob_end_flush() Faz

ob_end_flush() executa duas etapas no buffer de saída ativo mais interno (superior):

1. Ela libera o buffer — seu conteúdo é passado para o buffer pai ou enviado ao cliente se este for o último buffer da pilha.
2. Ela desativa esse buffer, removendo-o da pilha de buffers.

Ela retorna true em caso de sucesso, ou false se não houver nenhum buffer ativo (por exemplo, se você a chamar duas vezes ou nunca tiver chamado ob_start()). Quando falha, também emite um E_NOTICE.

Buffers formam uma pilha. Cada ob_start() empilha um novo buffer por cima. ob_end_flush() age somente sobre o buffer no topo, não sobre todos os buffers ao mesmo tempo. Verifique quantos estão abertos com ob_get_level().

Sintaxe

ob_end_flush(): bool

A função não recebe argumentos e retorna um boolean.

Exemplo Básico

<?php

ob_start();                       // start capturing output
echo "This will be buffered";     // goes into the buffer, not the screen yet
$ok = ob_end_flush();             // send the buffer out, then close it

var_dump($ok);                    // bool(true)

Saída:

This will be bufferedbool(true)

ob_start() abre o buffer, o echo vai para ele, e ob_end_flush() libera o texto para o navegador e encerra o buffering. O var_dump() é executado depois que o buffer é fechado, então sua saída é enviada diretamente.

Quando Devo Usar Isso?

O buffering de saída é mais útil quando você precisa decidir tardiamente o que fazer com a saída já gerada:

• Capturar, inspecionar ou modificar — armazene uma seção no buffer, leia-a com ob_get_contents(), opcionalmente reescreva-a e use ob_end_flush() para enviar o resultado (possivelmente modificado).
• Enviar cabeçalhos após a saída — como nada chega ao cliente enquanto o buffering está ativo, você ainda pode chamar header() ou setcookie() mesmo após ter usado echo em marcações. ob_end_flush() libera tudo depois que os cabeçalhos estiverem definidos.
• Templates aninhados — encapsule um buffer interno e libere-o para um buffer externo que realiza processamento adicional.

Se você quiser manter o texto capturado em uma variável em vez de enviá-lo, use ob_get_clean(). Se quiser descartar a saída, use ob_end_clean().

ob_end_flush() vs Funções Relacionadas

Uma forma rápida de lembrar: flush envia, clean descarta, get_ também entrega a string, e end_ fecha o buffer em vez de mantê-lo aberto.

Liberando Buffers Aninhados

Como ob_end_flush() só fecha um nível, você precisa chamá-la uma vez por buffer para desfazer completamente a pilha:

<?php

ob_start();                 // level 1
echo "outer ";

ob_start();                 // level 2
echo "inner";

echo ob_get_level();        // 2 — captured into level 2

ob_end_flush();             // level 2 flushes into level 1
ob_end_flush();             // level 1 flushes to the browser

Saída:

outer inner2

O echo interno e a contagem de níveis ficam ambos no buffer 2; o primeiro ob_end_flush() os mescla com o buffer 1, e o segundo envia tudo para o cliente.

Problemas Comuns

• Chamar sem um buffer ativo retorna false e gera um aviso. Use if (ob_get_level() > 0) como proteção se não tiver certeza de que um buffer está aberto.
• Ela não libera tudo — uma chamada fecha um buffer. Use um laço até que ob_get_level() seja 0 para desfazer todos os níveis.
• Não a confunda com flush(). O flush() simples empurra os buffers de escrita do PHP/SAPI para o cliente, mas não toca na pilha de buffering de saída.

Conclusão

ob_end_flush() envia o buffer de saída atual para o próximo nível e então fecha esse buffer. Use-a quando tiver utilizado ob_start() para capturar saída e agora quiser liberá-la. Lembre-se de que os buffers formam uma pilha, que a função age somente sobre o mais recente, e que as variantes clean/get_ oferecem as opções de descarte e retorno que você pode precisar.

Prática