Função PHP flush(): Enviar Saída ao Navegador Imediatamente

Por padrão, o PHP coleta o texto que seu script imprime (com echo, print, etc.) e o envia ao navegador em blocos — muitas vezes apenas quando o script termina. A função embutida flush() permite enviar imediatamente o que já foi produzido agora mesmo, para que o usuário veja a saída parcial antes que a página seja totalmente gerada. Esta página explica o que flush() faz, como difere de ob_flush(), os buffers que ficam entre seu script e o navegador, e quando utilizá-la realmente ajuda.

O Que a Função flush() Faz

flush(): void

flush() pede ao PHP que repasse qualquer saída que esteja retendo à camada abaixo — a SAPI e o servidor web. Ela não recebe argumentos e não retorna nada. Um uso comum é em scripts de longa duração que devem exibir progresso (uma linha de log, um contador) em vez de deixar o usuário olhando para uma página em branco até que tudo termine.

Dois limites importantes:

• flush() não afeta a própria camada de output buffering do PHP (aquela iniciada com ob_start()). Se o output buffering estiver ativo, o texto ainda está preso no buffer do PHP e flush() não tem nada a enviar. Você deve liberar essa camada primeiro com ob_flush() ou ob_end_flush().
• flush() não pode substituir o buffering feito pelo servidor web ou proxy (Apache mod_deflate, Nginx proxy_buffering, FastCGI, gzip). Esses ainda podem reter os dados até decidirem enviá-los.

Um Exemplo Básico

Quando nenhum output buffering do PHP está ativo, flush() sozinha é suficiente para enviar a saída atual:

<?php
echo "Starting a slow task...\n";
flush();        // send the line above to the browser now

sleep(2);       // pretend we are doing real work

echo "Done!\n";
?>

Sem a chamada a flush(), o usuário normalmente veria as duas linhas aparecerem juntas após 2 segundos. Com ela, "Starting a slow task..." pode chegar imediatamente.

flush() vs ob_flush()

Esta é a distinção que confunde as pessoas. O PHP pode empilhar dois buffers separados, e cada função *flush tem como alvo um diferente:

Quando o output buffering está ativo, você precisa de ambas, em ordem — ob_flush() primeiro para liberar o buffer do PHP, depois flush() para enviá-lo adiante:

<?php
ob_start();             // turn on PHP output buffering
echo "Buffered text\n";

ob_flush();             // PHP buffer -> SAPI buffer
flush();                // SAPI buffer -> browser
?>

Inverta a ordem ou omita ob_flush() e o texto ficará preso dentro do PHP. Se você quiser que o PHP faça flush automaticamente após cada echo, veja ob_implicit_flush().

Por Que Muitas Vezes "Não Funciona"

O streaming confiável de saída é mais difícil do que chamar uma função, porque várias camadas fazem buffer de forma independente:

• gzip / compressão — zlib.output_compression e o mod_deflate do Apache precisam acumular bytes suficientes antes de enviar. Desative a compressão para a resposta que você deseja transmitir em streaming.
• Buffering do servidor web / proxy — Nginx (proxy_buffering on), FastCGI e balanceadores de carga geralmente refazem o buffer da resposta.
• Renderização do navegador — alguns navegadores aguardam um número mínimo de bytes antes de renderizar; preencher a saída pode forçar uma renderização mais precoce.

Por causa disso, flush() é melhor tratada como uma dica, não como uma garantia. Para necessidades modernas de streaming (server-sent events, APIs com chunks) configure o servidor explicitamente em vez de depender apenas de flush().

Funções de Saída Relacionadas

• ob_flush() — faz flush do buffer de controle de saída do PHP.
• ob_end_flush() — faz flush e desativa o output buffering.
• ob_get_flush() — retorna o conteúdo do buffer e faz flush.
• PHP Output Control — visão geral de como as camadas de buffering se encaixam.
• fflush() — faz flush de escritas em buffer em um arquivo aberto (não no navegador).

Conclusão

flush() força o PHP a enviar a saída que já produziu em direção ao navegador em vez de esperar o script terminar. Lembre-se de que ela toca apenas o buffer SAPI/write: com ob_start() ativo, você deve chamar ob_flush() primeiro, e mesmo assim o servidor web ou a camada de compressão podem atrasar a entrega. Usada com esse entendimento, flush() é uma forma prática de transmitir progresso de scripts de longa duração.

Prática