Introduzione alla creazione e manipolazione di file PHP

PHP viene eseguito sul server, quindi può leggere e scrivere file reali su disco — report generati, HTML in cache, voci di log, CSV esportati, contenuti caricati dagli utenti e configurazioni. Questo capitolo tratta il flusso di lavoro fondamentale per creare e scrivere file: aprire un handle di file con la modalità corretta, scrivere i dati e chiudere l'handle. Spiega inoltre quando è meglio usare gli helper semplificati in una sola riga.

Esistono due famiglie di strumenti per la scrittura di file in PHP:

• Handle di stream — fopen() / fwrite() / fclose(). Ideali quando si scrive in modo incrementale (aggiungendo righe di log, trasmettendo output di grandi dimensioni) e si desidera un controllo preciso sulla modalità del file.
• Helper one-shot — file_put_contents(). Ideali quando si ha l'intera stringa in memoria e si vuole semplicemente scriverla su un file con una sola chiamata.

Utilizzeremo prima l'approccio con gli stream perché comprendere le modalità è la chiave di tutto il resto.

Creare e scrivere un file con fopen()

Per scrivere su un file, è necessario aprirlo prima con fopen(). Accetta il percorso del file e una stringa mode, e restituisce un handle di file (una risorsa) su cui operano le altre funzioni:

<?php
$file = fopen("example.txt", "w");   // open for writing, truncating the file
fwrite($file, "This is an example.\n");
fclose($file);                       // always close the handle

Cosa fa ciascuna riga:

• fopen("example.txt", "w") apre example.txt in modalità scrittura. Se il file non esiste viene creato; se esiste il suo contenuto viene cancellato (troncato a lunghezza zero).
• fwrite() scrive la stringa nel file e restituisce il numero di byte scritti (o false in caso di errore).
• fclose() svuota i dati nel buffer e rilascia l'handle. Saltarlo può lasciare dati non scritti fino alla fine dello script.

Un percorso relativo come "example.txt" viene risolto rispetto alla directory di lavoro corrente dello script. Per sicurezza e prevedibilità, preferire un percorso assoluto, ad es. __DIR__ . "/example.txt".

Modalità dei file

La modalità passata a fopen() determina se il file viene creato, troncato o aggiunto, e se è possibile leggerlo. Queste sono le modalità rilevanti per la creazione e la scrittura:

Usare "x" quando non si deve sovrascrivere un file esistente — ad esempio quando si scrive un file di lock. Usare "a" per i log, dove ogni esecuzione dovrebbe aggiungere al file anziché cancellarlo.

Aggiungere invece di sovrascrivere

Un errore molto comune è usare "w" per un log e chiedersi perché il file contenga sempre solo una riga. Aprire con "a" per mantenere il contenuto precedente e aggiungere alla fine:

<?php
$log = fopen("app.log", "a");        // append mode — never erases
fwrite($log, "[" . date("Y-m-d H:i:s") . "] User logged in\n");
fclose($log);

Eseguendo questo due volte, il file conterrà due righe con timestamp invece di una.

La scorciatoia: file_put_contents()

Quando si ha già il contenuto completo come stringa, file_put_contents() esegue apertura, scrittura e chiusura in una singola chiamata:

<?php
// Overwrite (or create) the file with this exact content:
file_put_contents("greeting.txt", "Hello, world!\n");

// Append instead of overwriting:
file_put_contents("app.log", "another line\n", FILE_APPEND);

Restituisce il numero di byte scritti, o false in caso di errore. È la scelta più pulita per payload piccoli già in memoria. Usare fopen()/fwrite() quando si scrive in un ciclo o si deve tenere l'handle aperto attraverso più operazioni.

Rileggere ciò che si è scritto

Per verificare una scrittura, aprire il file in modalità lettura ("r") e leggerlo. Il capitolo correlato PHP File Open/Read lo tratta in profondità, ma la versione con stream è:

<?php
$file = fopen("example.txt", "r");
$contents = fread($file, filesize("example.txt"));
fclose($file);
echo $contents;

Qui fread() legge fino a filesize("example.txt") byte — l'intero file — in $contents. Per un'istruzione in una sola riga, file_get_contents() legge l'intero file in una stringa senza dover gestire alcun handle.

Gestire gli errori e i file mancanti

fopen() restituisce false (ed emette un avviso) se non riesce ad aprire il file — permessi errati, una directory inesistente o un disco in sola lettura. Verificare sempre prima di scrivere:

<?php
$file = fopen("/no/such/dir/example.txt", "w");
if ($file === false) {
    echo "Could not open the file for writing.";
} else {
    fwrite($file, "ok");
    fclose($file);
}

Prima di leggere un file non creato nella stessa esecuzione, verificarne l'esistenza con file_exists() per evitare avvisi da filesize() o fread().

Altre funzioni utili per i file

Oltre alla creazione e alla scrittura, PHP include un toolkit completo per la gestione dei file:

• file_get_contents() — legge un intero file in una stringa con una sola chiamata.
• file_put_contents() — scrive una stringa su un file con una sola chiamata.
• file_exists() — verifica se un percorso esiste prima di agire su di esso.
• unlink() — elimina un file.
• rename() — rinomina o sposta un file.
• copy() — copia un file in un nuovo percorso.

Per i file caricati da un modulo, vedere PHP File Upload, e per una panoramica più ampia dell'API del filesystem, vedere PHP File Handling.

Riepilogo

• Aprire un file con fopen($path, $mode); la modalità controlla il comportamento di creazione/troncamento/aggiunta.
• Usare "w" per sovrascrivere, "a" per aggiungere e "x" per rifiutare di sovrascrivere un file esistente.
• fwrite() scrive e fclose() svuota il buffer e rilascia l'handle — chiudere sempre.
• Per scrivere intere stringhe, file_put_contents() è l'alternativa concisa in una sola chiamata.
• Verificare il valore restituito da fopen() e usare file_exists() per scrivere codice robusto e privo di avvisi.

Esercitazione