fread()

La funzione fread() legge un numero scelto di byte da un file aperto. A differenza degli helper che caricano l'intero file in una sola chiamata, fread() offre un controllo preciso su quanti byte leggere alla volta — esattamente ciò di cui hai bisogno per file di grandi dimensioni, dati binari o contenuto in streaming. Questa pagina tratta la sintassi, il valore restituito, come leggere un file in blocchi sicuri e le insidie più comuni.

Sintassi

fread(resource $stream, int $length): string|false

fread() si interrompe non appena si verifica una delle seguenti condizioni: sono stati letti $length byte, viene raggiunta la fine del file (EOF), un pacchetto diventa disponibile (per stream di rete), oppure sono stati letti 8192 byte dopo che il buffer dello stream è stato riempito (per file non regolari). Restituisce i byte letti come string, oppure false in caso di errore.

fread() è binary-safe — legge i byte esattamente così come sono, quindi funziona per immagini, PDF e altri file non testuali, non solo per testo normale.

Lettura di un file intero

L'uso più semplice è leggere un intero file in una sola chiamata, passando la sua dimensione come $length:

<?php

$filename = 'myfile.txt';
$file = fopen($filename, 'r');

if ($file) {
    $data = fread($file, filesize($filename));
    echo $data;
    fclose($file);
}

Qui fopen() apre il file in modalità sola lettura ('r'), filesize() riporta quanti byte contiene il file e fread() ne legge esattamente quel numero. Associa sempre fopen() a fclose() per rilasciare l'handle del file.

Per leggere un intero file quando non hai bisogno di un handle, file_get_contents() è un'alternativa in una sola riga. Ricorri a fread() quando hai bisogno di controllare la dimensione della lettura o di elaborare il file in modo incrementale.

Lettura di un file a blocchi

Per i file di grandi dimensioni non dovresti caricare tutto in memoria in una volta. Leggi un blocco di dimensione fissa per ogni iterazione e fermati alla fine del file usando feof():

<?php

$file = fopen('large.log', 'r');

if ($file) {
    while (!feof($file)) {
        $chunk = fread($file, 1024); // read up to 1 KB at a time
        echo $chunk;
    }
    fclose($file);
}

In questo modo l'utilizzo della memoria rimane costante indipendentemente dalla dimensione del file, perché in memoria si trova un solo blocco da 1 KB alla volta. Aumenta la dimensione del blocco (ad esempio 8192) per scambiare più memoria con un numero inferiore di chiamate di lettura.

Valore restituito e gestione degli errori

fread() restituisce una string con i byte letti. Alla fine del file restituisce una string vuota "", mentre in caso di errore restituisce false. Poiché "" e false sono entrambi falsy, usa un controllo rigoroso quando devi distinguerli:

<?php

$file = fopen('data.bin', 'rb');

if ($file === false) {
    exit('Could not open the file.');
}

$bytes = fread($file, 16);

if ($bytes === false) {
    echo 'Read failed.';
} else {
    echo 'Read ' . strlen($bytes) . " bytes.\n";
}

fclose($file);

Nota la modalità 'rb': su Windows, aprire in modalità binaria (b) impedisce la traduzione dei fine riga che corromperebbe i dati binari. È innocua su altre piattaforme, quindi è buona prassi per qualsiasi file non testuale.

Insidie comuni

• $length è un massimo, non una garanzia. Una singola chiamata a fread() può restituire meno byte del richiesto (ad esempio vicino all'EOF o su uno stream di rete). Per leggere una quantità esatta, esegui un ciclo finché non hai raccolto abbastanza byte o raggiunto l'EOF.
• Il file deve essere aperto in una modalità leggibile. Modalità come 'w' aprono solo per la scrittura; usa 'r', 'r+', 'a+', ecc. Consulta fopen() per l'elenco completo delle modalità.
• Non dimenticare fclose(). La perdita di handle può esaurire i descrittori di file disponibili negli script a lunga esecuzione.
• Vuoi leggere per righe? Se preferisci una riga alla volta anziché un conteggio di byte, fgets() è lo strumento più adatto.

Funzioni correlate

• fopen() — apre un file e restituisce il puntatore di cui fread() ha bisogno.
• fwrite() — la controparte che scrive byte in un file.
• fgets() — legge una singola riga invece di un conteggio di byte.
• feof() — verifica la fine del file durante un ciclo.
• file-get-contents() — legge un intero file in una sola chiamata.
• fclose() — chiude l'handle del file al termine.

Conclusione

fread() è lo strumento PHP per leggere un numero preciso di byte da un file aperto. Usalo con filesize() per acquisire un intero file, oppure eseguilo in un ciclo con feof() per elaborare in streaming file di grandi dimensioni in blocchi che rispettano la memoria. Ricorda che $length è un limite superiore, apri i file binari con il flag b e chiudi sempre l'handle con fclose().

Esercizio