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

Por padrão, o PHP mantém sua saída em um buffer e a envia ao cliente de uma vez só. Em alguns casos, você quer enviar o que já foi produzido até o momento ao navegador sem encerrar o buffer — por exemplo, para transmitir um relatório longo linha por linha ou exibir progresso durante uma tarefa demorada. A função ob_flush() faz exatamente isso: ela envia o conteúdo do buffer de saída ativo para o próximo nível e o esvazia, mantendo o buffering ativo para que você continue coletando saída. Este capítulo explica como ob_flush() se encaixa na cadeia de buffer de saída do PHP, quando utilizá-la e as armadilhas que costumam pegar as pessoas de surpresa.

O que ob_flush() Faz

ob_flush() envia o conteúdo do buffer de saída mais alto para o próximo nível — o próximo buffer na pilha, ou a camada de escrita interna do PHP se este for o único buffer. Após o flush, esse buffer é esvaziado, mas permanece aberto, de modo que echos subsequentes são capturados novamente.

Signature:  ob_flush(): void
Returns:    nothing (void); emits a warning if no buffer is active
PHP:        4.0+ (return type became void in PHP 8.0)

Dois conceitos são fáceis de confundir:

• ob_flush() move dados para fora do buffer do PHP, mas não garante que eles cheguem ao navegador. Pode haver outro buffer acima dele, além do próprio buffer de escrita do PHP e o buffer do servidor web.
• flush() empurra os buffers de escrita do PHP em direção ao cliente. Para realmente enviar bytes pela rede, normalmente se chama ambos, nessa ordem: ob_flush() e depois flush().

Ela deve ser usada em conjunto com ob_start(). Chamar ob_flush() sem nenhum buffer ativo gera um notice/warning e não faz nada.

Sintaxe

ob_flush();

Não recebe argumentos e não retorna nenhum valor.

Exemplo Básico

Habilite o buffering, escreva algo e faça o flush:

<?php

ob_start();              // 1. Enable output buffering
echo "This will be buffered";
ob_flush();              // 2. Flush PHP buffer to the next level
flush();                 // 3. Push it toward the client

Saída:

This will be buffered

ob_start() abre um buffer, o echo é capturado nele, ob_flush() libera esse texto e flush() o empurra em direção ao navegador. É fundamental notar que o buffer ainda está aberto após isso — você poderia fazer echo e flush novamente.

Transmitindo Saída Progressivamente

O uso real mais comum de ob_flush() é enviar a saída em partes para que o usuário veja os resultados à medida que são produzidos, em vez de esperar o script inteiro terminar:

<?php

ob_start();

for ($i = 1; $i <= 5; $i++) {
    echo "Processing item $i\n";
    ob_flush();          // hand this line to the next level
    flush();             // and on toward the browser
    // sleep(1);         // (a real task would do work here)
}

Saída:

Processing item 1
Processing item 2
Processing item 3
Processing item 4
Processing item 5

Em um servidor em produção com sleep(1) descomentado, cada linha apareceria com um segundo de intervalo em vez de todas no final.

ob_flush() vs. ob_end_flush() vs. ob_get_clean()

Escolher a função de "flush" errada é a fonte mais comum de bugs. Elas diferem em dois aspectos: se o buffer permanece aberto e para onde o conteúdo vai.

Use ob_flush() quando quiser emitir progresso mas continuar com o buffering. Use ob_end_flush() quando tiver concluído completamente. Use ob_get_clean() quando quiser capturar o buffer em uma variável em vez de enviá-lo.

Armadilhas Comuns

• O buffering do servidor ainda pode reter a saída. Apache, Nginx (buffering FastCGI), compressão gzip e proxies podem guardar seus bytes até terem "conteúdo suficiente". ob_flush() + flush() controlam apenas o lado do PHP.
• zlib.output_compression quebra o streaming. Quando a compressão de saída gzip está ativada, os flushes intermediários geralmente ficam no buffer para compressão, portanto os fragmentos não vão aparecer aos poucos. Desative-a para endpoints de streaming.
• Sem buffer = warning. Chamar ob_flush() sem um ob_start() correspondente gera um warning. Verifique o nível ativo com ob_get_level() se não tiver certeza.
• Ele esvazia o buffer. Após ob_flush(), o buffer é limpo, portanto você não pode ler seu conteúdo anterior depois disso.
• Forçar flush imediato globalmente. ob_implicit_flush(true) faz com que cada instrução de saída faça flush automaticamente, eliminando a necessidade de chamar ob_flush() após cada echo.

Conclusão

ob_flush() envia o buffer de saída atual adiante enquanto mantém o buffering habilitado, tornando-o a ferramenta certa para transmitir progresso ou respostas grandes de forma incremental. Lembre-se da cadeia: ob_start() abre o buffer, ob_flush() libera seu conteúdo para o próximo nível e flush() os empurra em direção ao cliente — e que o buffering do servidor ou a compressão gzip ainda podem atrasar a entrega independentemente do que o código PHP faz.

Prática