fwrite()

Cos'è la funzione fwrite()?

fwrite() è una funzione PHP integrata che scrive una string in un file aperto. La scrittura inizia dalla posizione corrente del puntatore di file e fa avanzare quel puntatore del numero di byte scritti, quindi le chiamate consecutive si accodano l'una all'altra invece di sovrascriversi. È il metodo standard di basso livello per scrivere su file in PHP ed è comunemente disponibile anche come fputs() (le due funzioni sono identiche).

Questa pagina tratta la sintassi, l'argomento opzionale length, le modalità di file che controllano dove e come vengono scritti i dati, i valori restituiti, la gestione degli errori e le operazioni quotidiane per cui si utilizzerà fwrite().

Sintassi

fwrite(resource $stream, string $data, ?int $length = null): int|false

Valore restituito: il numero di byte effettivamente scritti, oppure false in caso di errore. Poiché su alcuni stream è possibile una scrittura parziale (meno byte di strlen($data)), il codice robusto verifica il valore restituito invece di presumere il successo.

Nella maggior parte dei casi l'argomento length non è necessario. fwrite($file, $data) scrive già l'intera string. Passare una lunghezza solo quando si vuole deliberatamente troncare l'output ai primi N byte.

Un Esempio di Base

<?php

$filename = 'myfile.txt';
$file = fopen($filename, 'w');     // open for writing (truncates the file)

if ($file === false) {
    exit("Could not open $filename for writing");
}

$bytes = fwrite($file, "Hello, world!");
fclose($file);

echo "Wrote $bytes bytes."; // Wrote 13 bytes.

Sono sempre coinvolti tre passaggi:

1. Aprire il file con fopen() in una modalità che consenta la scrittura.
2. Chiamare fwrite() una o più volte per inviare dati allo stream.
3. Chiudere il file con fclose() per svuotare il buffer e rilasciare l'handle.

"Hello, world!" contiene 13 caratteri, quindi fwrite() restituisce 13.

Modalità di File: Dove Vanno i Byte

Il comportamento di fwrite() è determinato quasi interamente dalla modalità passata a fopen(). Questa è la fonte più comune di confusione, quindi vale la pena memorizzarla:

Se il file risulta vuoto o perde i dati precedenti, quasi certamente è stato aperto con 'w' quando si intendeva usare 'a'.

Accodamento Instead of Overwriting

<?php

$log = fopen('app.log', 'a');           // 'a' keeps existing lines
fwrite($log, "User logged in\n");       // \n adds a newline
fwrite($log, "Order placed\n");
fclose($log);

Ogni esecuzione di questo script aggiunge altre due righe ad app.log invece di azzerarlo.

Scrittura di Più Righe

fwrite() scrive esattamente i byte forniti — non aggiunge interruzioni di riga. Bisogna includere \n manualmente (dentro virgolette doppie, affinché l'escape venga interpretato):

<?php

$file = fopen('names.txt', 'w');

$names = ['Alice', 'Bob', 'Carol'];
foreach ($names as $name) {
    fwrite($file, $name . PHP_EOL); // PHP_EOL = OS-correct line ending
}

fclose($file);

PHP_EOL corrisponde a \n su Unix/macOS e \r\n su Windows, rendendo i file di testo portabili.

Verificare Sempre il Valore Restituito

Disco pieno, problemi di permessi e pipe interrotte possono causare la mancata riuscita o il completamento parziale della scrittura. Trattare il valore restituito come fonte di verità:

<?php

$file = fopen('report.txt', 'w');
if ($file === false) {
    throw new RuntimeException('Unable to open report.txt');
}

$data    = str_repeat('x', 1000);
$written = fwrite($file, $data);

if ($written === false || $written < strlen($data)) {
    fclose($file);
    throw new RuntimeException('Write failed or incomplete');
}

fclose($file);
echo "OK: $written bytes written";

fwrite() vs file_put_contents()

Per una singola scrittura immediata, file_put_contents() è più conciso — apre, scrive e chiude con una sola chiamata:

<?php

// Equivalent of the basic example above, in one line:
file_put_contents('myfile.txt', 'Hello, world!');

Preferire fwrite() quando si ha bisogno di mantenere il file aperto durante molte scritture (cicli, streaming, logging), passare opzioni come il blocco, o scrivere in modo incrementale senza ricostruire l'intera string in memoria.

Insidie Comuni

• 'w' tronca immediatamente — nel momento in cui fopen($f, 'w') ha successo, il contenuto precedente è perso, anche se non si chiama mai fwrite().
• Nessuna interruzione di riga automatica — bisogna aggiungere \n / PHP_EOL manualmente.
• Dimenticare fclose() — i dati possono rimanere in un buffer e non raggiungere mai il disco finché l'handle non viene chiuso (o lo script non termina).
• Le virgolette singole non espandono gli escape — 'Line\n' scrive un backslash letterale seguito da n. Usare "Line\n" per un vero a capo.
• Il limite di length è in byte — con testo UTF-8 multi-byte, un limite in byte può spezzare un carattere a metà.

Conclusione

fwrite() è la funzione principale di PHP per scrivere string in un file aperto. Padroneggiare il ciclo in tre fasi apri–scrivi–chiudi, scegliere la modalità fopen() corretta ('w' per sostituire, 'a' per accodare), aggiungere manualmente le interruzioni di riga e verificare il valore restituito permette di scrivere qualsiasi cosa, dai semplici file di testo ai log applicativi durevoli.

Funzioni Correlate

• fopen() — aprire il file prima di scrivere
• fclose() — svuotare e chiudere l'handle in seguito
• fread() e fgets() — leggere i dati indietro
• file_put_contents() — scrivere un intero file con una sola chiamata
• feof() — rilevare la fine di un file durante la lettura

Pratica