fflush()

Introdução à Função fflush() do PHP

A função fflush() em PHP força que quaisquer dados ainda presentes no buffer de escrita de um ponteiro de arquivo sejam gravados no stream subjacente imediatamente, em vez de aguardar o preenchimento do buffer ou o fechamento do stream.

Quando você chama fwrite(), o PHP não necessariamente envia os bytes diretamente para o disco. Por questões de desempenho, os dados são coletados em um buffer na memória e gravados em blocos maiores. Isso geralmente é o que você deseja — mas às vezes é necessário que os dados sejam persistidos agora: um arquivo de log monitorado em tempo real, um worker de longa execução que outro processo está lendo, ou um script que pode ser encerrado antes de terminar. fflush() é a função que diz "não espere, grave o que você tem."

Esta página abrange a sintaxe, os parâmetros, o valor de retorno e vários exemplos executáveis, além das armadilhas que pegam as pessoas de surpresa — incluindo a diferença crucial entre fflush() e a sincronização de disco em nível de sistema operacional.

Sintaxe

A sintaxe da função fflush() é a seguinte:

A sintaxe PHP de fflush()

bool fflush ( resource $stream )

• stream: o ponteiro de arquivo a ser descarregado

Parâmetros

A função fflush() recebe um parâmetro obrigatório:

• $stream: O ponteiro de arquivo a ser descarregado. Deve ser um recurso de stream válido e gravável — tipicamente um retornado por fopen(). Streams abertos somente para leitura (modo 'r') não têm nada a descarregar.

Valor de Retorno

fflush() retorna true em caso de sucesso ou false em caso de falha. Falha quando o recurso não é um stream aberto válido ou quando a escrita subjacente não pode ser concluída; um aviso pode ser emitido. Como as falhas são raras, mas reais (disco cheio, pipe quebrado), verifique o valor de retorno quando a escrita não pode ser perdida:

<?php

if (fflush($stream) === false) {
    // The buffered data could not be written — handle it (log, retry, abort).
}

Exemplos

Exemplo 1: Descarregar um ponteiro de arquivo

Abra um arquivo, escreva dados e, em seguida, descarregue para que os bytes atinjam o stream antes que o script continue:

Descarregar um ponteiro de arquivo em PHP

<?php

$fileHandle = fopen('example.txt', 'w');
fwrite($fileHandle, 'Hello, World!');

if (fflush($fileHandle)) {
    echo "Buffer flushed to the stream.\n";
}

fclose($fileHandle);

Saída:

Buffer flushed to the stream.

Exemplo 2: Um log continuamente descarregado

Um worker que acrescenta dados a um arquivo de log e descarrega após cada entrada, para que outro processo possa executar tail -f no arquivo e ver as linhas aparecerem em tempo real, em vez de em rajadas:

Logging em tempo real com fflush()

<?php

$log = fopen('worker.log', 'a');

foreach (['started', 'processing', 'done'] as $event) {
    fwrite($log, date('c') . " {$event}\n");
    fflush($log); // each line is visible immediately, not only at fclose()
}

fclose($log);

Sem a chamada fflush(), as três linhas normalmente apareceriam apenas quando o buffer estivesse cheio ou quando fclose() fosse executado no final.

fflush() vs. fclose()

Você não precisa de fflush() logo antes de fclose() — fclose() descarrega automaticamente quaisquer dados em buffer restantes antes de fechar o recurso. Use fflush() somente quando precisar que os dados sejam gravados enquanto o arquivo ainda está aberto.

fflush() não garante que os dados estejam no disco

Este é o equívoco mais comum. fflush() empurra o buffer do PHP para o sistema operacional, mas o SO mantém seu próprio cache de escrita. Após fflush(), os bytes ainda podem estar no cache do SO em vez de no disco físico. Se a máquina perder energia imediatamente após, os dados podem ser perdidos.

Para forçar o SO a confirmar os dados no armazenamento durável, utilize fsync() (PHP 8.1+):

<?php

$file = fopen('important.txt', 'w');
fwrite($file, 'critical data');
fflush($file); // PHP buffer -> OS
fsync($file);  // OS cache -> physical disk (PHP 8.1+)
fclose($file);

Controlando o próprio buffer

Se você quiser alterar quanto o PHP armazena em buffer antes de gravar automaticamente — em vez de descarregar sob demanda — use set_file_buffer(). Definir o tamanho do buffer como 0 desativa completamente o buffer, de modo que cada fwrite() seja gravado diretamente sem precisar de um fflush() explícito.

Observação sobre o buffer de saída

Não confunda fflush() com as funções de buffer de saída do PHP, como ob_flush() e flush(). fflush() opera em um recurso de arquivo/stream (arquivos, sockets, pipes). ob_flush() descarrega o buffer de saída interno do PHP (o corpo da página) em direção ao servidor web ou ao cliente. São mecanismos não relacionados que compartilham apenas a palavra "flush".

Conclusão

Em conclusão, a função fflush() é uma função PHP útil que garante que os dados em buffer sejam gravados imediatamente em um stream de arquivo. É essencial para aplicações que exigem persistência de dados em tempo real, como sistemas de logging ou scripts de processamento de dados.

Usando os exemplos fornecidos neste artigo, você agora deve ser capaz de usar a função fflush() no seu código PHP com facilidade. Se você tiver alguma dúvida ou preocupação sobre o uso da função fflush() em PHP, sinta-se à vontade para entrar em contato conosco. Teremos prazer em ajudá-lo.

Prática