fopen()

Cos'è la funzione fopen()?

La funzione fopen() è una funzione PHP integrata che apre un file (o un URL) e restituisce un puntatore di file — un handle di risorsa che si passa poi a funzioni come fread(), fwrite(), fgets() e fclose() per leggere, scrivere e chiudere effettivamente lo stream. In caso di errore restituisce false ed emette un E_WARNING.

Quasi ogni operazione su file in PHP che legge o scrive in modo incrementale inizia con fopen(). (Per letture e scritture singole si ricorre solitamente a file_get_contents() e file_put_contents() — vedi Quando non usare fopen().)

Sintassi

fopen(string $filename, string $mode, bool $use_include_path = false, $context = null): resource|false

Restituisce una risorsa puntatore di file in caso di successo, oppure false in caso di errore.

Modalità di fopen()

L'argomento $mode è la parte che viene sbagliata più spesso. Controlla se il file viene letto, scritto o entrambi, dove inizia il puntatore interno e se il file viene troncato oppure deve già esistere.

È possibile aggiungere b (binario, ad es. 'rb') o t (testo) a qualsiasi modalità. Usare sempre 'b' per file non testuali come immagini o eseguibili — su Windows la modalità testo traduce silenziosamente le terminazioni di riga e corrompe i dati binari. Su Unix le due modalità sono identiche, quindi 'b' è l'impostazione sicura predefinita ovunque.

Esempio base: leggere un file

Aprire un file in modalità lettura, leggerne il contenuto e poi chiuderlo. Verificare sempre il valore restituito prima di usare l'handle, e chiamare sempre fclose() quando si è finito in modo che il sistema operativo possa rilasciare il descrittore.

<?php

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

if ($file === false) {
    echo "Unable to open file!";
} else {
    echo fread($file, filesize($filename));
    fclose($file);
}

Apriamo myfile.txt in modalità sola lettura e controlliamo l'handle con un confronto stretto === false — questo è importante perché una risorsa valida è truthy, ma lo sono anche alcuni valori non di errore, quindi i controlli non stretti possono creare problemi in seguito.

Scrivere su un file

Aprire con 'w' crea il file se non esiste e lo tronca a lunghezza zero se esiste. Usare 'a' invece quando si vuole aggiungere alla fine senza cancellare ciò che c'è già (utile per i file di log).

<?php

$file = fopen('log.txt', 'w');     // create / overwrite
fwrite($file, "First line\n");
fwrite($file, "Second line\n");
fclose($file);

$file = fopen('log.txt', 'a');     // append, keep existing content
fwrite($file, "Appended later\n");
fclose($file);

echo file_get_contents('log.txt');

Questo stampa tutte e tre le righe perché 'a' ha aggiunto al file invece di sostituirlo. Vedi fwrite() per la parte di scrittura e feof() per rilevare la fine del file durante un ciclo.

Lettura riga per riga

Per file di grandi dimensioni, non leggere tutto in memoria in una volta sola. Abbina fopen() a fgets() e feof() per elaborare una riga alla volta in streaming:

<?php

$file = fopen('myfile.txt', 'r');
if ($file) {
    while (!feof($file)) {
        $line = fgets($file);
        if ($line !== false) {
            echo $line;
        }
    }
    fclose($file);
}

Errori comuni

• Dimenticare di controllare false. Se il percorso è errato o i permessi negano l'accesso, fopen() restituisce false e avvisa. Chiamare fread() su false lancia un TypeError in PHP 8+.
• Non chiudere l'handle. I descrittori aperti sono una risorsa limitata; perderli in un processo a lunga esecuzione esaurisce eventualmente il limite del sistema operativo. Chiamare sempre fclose(), idealmente in un blocco finally.
• Modalità errata. Usare 'w' quando si intendeva 'r' cancella silenziosamente il file. Ricorrere a 'x' quando si vuole specificamente che la creazione fallisca se il file esiste già.
• Percorsi relativi. Vengono risolti rispetto alla directory di lavoro corrente dello script, che non è sempre quella attesa. Preferire percorsi assoluti o __DIR__ . '/file.txt'.

Quando non usare fopen()

Se si ha bisogno dell'intero file come string, o di scrivere una string in un file con una sola chiamata, si può evitare la sequenza apri/leggi/chiudi:

Ricorrere a fopen() quando si ha bisogno di un controllo granulare e incrementale — leggere file enormi a blocchi, aggiungere a un log, o lavorare con stream non file come php://stdin.

Conclusione

fopen() è la base della gestione dei file a basso livello in PHP: restituisce un puntatore di file da cui si legge con fread() / fgets(), su cui si scrive con fwrite(), e che si rilascia sempre con fclose(). Scegliere la modalità giusta, controllare il valore restituito e chiudere l'handle, e il resto delle funzioni di gestione dei file di PHP seguirà naturalmente.

Pratica