fflush()

Introduzione alla funzione PHP fflush()

La funzione fflush() in PHP forza la scrittura immediata di tutti i dati ancora presenti nel buffer di scrittura di un puntatore di file nello stream sottostante, senza attendere che il buffer si riempia o che lo stream venga chiuso.

Quando si chiama fwrite(), PHP non invia necessariamente i byte direttamente al disco. Per ragioni di prestazioni, i dati vengono raccolti in un buffer in memoria e scritti in blocchi più grandi. Questo è solitamente il comportamento desiderato — ma a volte è necessario che i dati vengano scritti immediatamente: un file di log monitorabile con tail, un worker di lunga durata che un altro processo sta leggendo, o uno script che potrebbe essere interrotto prima di terminare. fflush() è la funzione che dice "non aspettare, scrivi ciò che hai."

Questa pagina tratta la sintassi, i parametri, il valore di ritorno e diversi esempi eseguibili, oltre agli errori più comuni — inclusa la differenza cruciale tra fflush() e la sincronizzazione del disco a livello di sistema operativo.

Sintassi

La sintassi della funzione fflush() è la seguente:

La sintassi PHP di fflush()

bool fflush ( resource $stream )

• stream: il puntatore di file da svuotare

Parametri

La funzione fflush() accetta un parametro obbligatorio:

• $stream: Il puntatore di file da svuotare. Deve essere una risorsa stream valida e scrivibile — tipicamente quella restituita da fopen(). Gli stream aperti in sola lettura (modalità 'r') non hanno nulla da svuotare.

Valore di ritorno

fflush() restituisce true in caso di successo o false in caso di errore. Fallisce quando la risorsa non è uno stream aperto valido o quando la scrittura sottostante non può essere completata; potrebbe essere emesso un avviso. Poiché i fallimenti sono rari ma reali (disco pieno, pipe interrotta), è opportuno verificare il valore di ritorno quando la scrittura non può andare persa:

<?php

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

Esempi

Esempio 1: Svuotare un puntatore di file

Aprire un file, scrivere dati, quindi svuotare il buffer in modo che i byte raggiungano lo stream prima che lo script continui:

Svuotare un puntatore di file in PHP

<?php

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

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

fclose($fileHandle);

Output:

Buffer flushed to the stream.

Esempio 2: Un log con svuotamento continuo

Un worker che aggiunge voci a un file di log e svuota il buffer dopo ogni riga, in modo che un altro processo possa usare tail -f sul file e vedere le righe apparire in tempo reale anziché a blocchi:

Logging in tempo reale con 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);

Senza la chiamata a fflush(), le tre righe di norma apparirebbero solo quando il buffer si riempie o quando fclose() viene eseguito alla fine.

fflush() vs. fclose()

Non è necessario usare fflush() subito prima di fclose() — fclose() svuota automaticamente i dati ancora in buffer prima di chiudere la risorsa. Usare fflush() solo quando si ha bisogno che i dati vengano scritti mentre il file è ancora aperto.

fflush() non garantisce che i dati siano su disco

Questo è il malinteso più comune. fflush() trasferisce il buffer di PHP al sistema operativo, ma il sistema operativo mantiene la propria cache di scrittura. Dopo fflush() i byte potrebbero trovarsi ancora nella cache del sistema operativo anziché sul disco fisico. Se la macchina perde alimentazione immediatamente dopo, i dati possono andare persi.

Per forzare il sistema operativo a salvare i dati nella memoria persistente, seguire con 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);

Controllo del buffer stesso

Se si desidera modificare la quantità di dati che PHP mette in buffer prima di scrivere automaticamente — anziché svuotare su richiesta — usare set_file_buffer(). Impostare la dimensione del buffer a 0 disabilita completamente il buffering, in modo che ogni fwrite() venga scritto direttamente senza necessità di un fflush() esplicito.

Nota sull'output buffering

Non bisogna confondere fflush() con le funzioni di output buffering di PHP come ob_flush() e flush(). fflush() opera su una risorsa file/stream (file, socket, pipe). ob_flush() svuota il buffer di output interno di PHP (il corpo della pagina) verso il server web o il client. Sono meccanismi distinti che condividono per coincidenza la parola "flush".

Conclusione

In conclusione, la funzione fflush() è una funzione PHP utile che garantisce la scrittura immediata dei dati in buffer su uno stream di file. È essenziale per le applicazioni che richiedono persistenza dei dati in tempo reale, come i sistemi di logging o gli script di elaborazione dati.

Grazie agli esempi forniti in questo articolo, dovresti ora essere in grado di usare la funzione fflush() nel tuo codice PHP con facilità. Se hai domande o dubbi sull'uso della funzione fflush() in PHP, non esitare a contattarci. Saremo lieti di aiutarti.

Pratica