file_put_contents()

La funzione file_put_contents() scrive una string in un file con una singola chiamata. È il moderno sostituto in una riga della sequenza classica fopen() → fwrite() → fclose(): PHP apre il file, scrive i dati e chiude l'handle per te. Questa pagina tratta la sintassi, i parametri, il valore restituito, i flag per accodare e bloccare, e gli errori più comuni in cui ci si imbatte.

Sintassi

file_put_contents(string $filename, mixed $data, int $flags = 0, ?resource $context = null): int|false

Parametri

Valore restituito

file_put_contents() restituisce il numero di byte scritti, oppure false in caso di errore. Poiché 0 è un risultato valido (ma falsy) quando si scrive una string vuota, verifica sempre l'errore con il confronto stretto === false anziché un test di veridicità generico.

Scrittura di un file

Per impostazione predefinita la funzione sovrascrive il contenuto esistente del file (o crea il file se mancante):

<?php

$filename = 'myfile.txt';
$data     = 'This is some data to be written to the file.';

$bytes = file_put_contents($filename, $data);

if ($bytes === false) {
    echo "Failed to write to $filename";
} else {
    echo "Wrote $bytes bytes to $filename";
}

Output:

Wrote 44 bytes to myfile.txt

Il conteggio restituito, 44, è la lunghezza della string in byte.

Accodare invece di sovrascrivere

Passa il flag FILE_APPEND per aggiungere contenuto alla fine del file anziché sostituirne il contenuto — comodo per i file di log:

<?php

$log = 'app.log';

file_put_contents($log, "First line\n", FILE_APPEND);
file_put_contents($log, "Second line\n", FILE_APPEND);

echo file_get_contents($log);

Output:

First line
Second line

Senza FILE_APPEND, la seconda chiamata cancellerebbe la prima riga.

Bloccare il file durante la scrittura

Se più processi potrebbero scrivere sullo stesso file contemporaneamente, aggiungi LOCK_EX per acquisire un blocco esclusivo per la durata della scrittura. Combina i flag con l'operatore OR bit a bit (|):

<?php

file_put_contents('counter.txt', "ping\n", FILE_APPEND | LOCK_EX);

Questo impedisce a due writer di sovrapporre il loro output e corrompere il file.

Scrittura di un array

Quando $data è un array, i suoi elementi string vengono concatenati senza separatore. Uniscili tu stesso se hai bisogno di delimitatori:

<?php

$lines = ['apple', 'banana', 'cherry'];

file_put_contents('fruits.txt', implode("\n", $lines));

echo file_get_contents('fruits.txt');

Output:

apple
banana
cherry

Errori comuni

• Fallimento silenzioso per i permessi. Se la directory non è scrivibile, la chiamata restituisce false ed emette un avviso — non lancia un'eccezione. Controlla il valore restituito (=== false) oppure racchiudi la chiamata e ispeziona error_get_last().
• La directory padre deve esistere. file_put_contents() crea il file ma non le directory mancanti. Chiama prima mkdir($dir, 0777, true) se necessario.
• FILE_APPEND non è lo stesso della sovrascrittura. Dimenticare il flag è la causa più comune del "il mio log viene continuamente cancellato."
• I dati vuoti sono validi. Scrivere '' restituisce 0, che è falsy — usa === false per non confondere una scrittura vuota riuscita con un errore.

Funzioni correlate

• file_get_contents() — la controparte in lettura che carica l'intero file in una string.
• fwrite() — scrittura di livello inferiore quando si ha bisogno di un handle aperto (ad es. molte piccole scritture in un ciclo).
• fopen() — apre un handle di file per la lettura o la scrittura in streaming.
• file_exists() — verifica se un file è presente prima di scrivere.

Conclusione

file_put_contents() è il modo più semplice per scrivere una string in un file in PHP: una singola chiamata apre, scrive e chiude il file. Usa FILE_APPEND per aggiungere contenuto a un file, LOCK_EX per writer concorrenti, e verifica sempre il successo con un controllo stretto === false.

Esercitazione