fputs()

Che cos'è la funzione fputs()?

La funzione fputs() scrive una string in un file aperto. È lo strumento principale per salvare testo su disco in PHP: log, esportazioni, file di configurazione generati e così via.

La cosa più importante su fputs() è che è un alias di fwrite() — le due funzioni sono identiche in ogni aspetto. PHP mantiene fputs() perché il nome si legge come "file put string," familiare ai programmatori provenienti dal C. Il codice moderno preferisce di solito fwrite(), ma entrambe si comportano allo stesso modo, quindi tutto ciò che segue si applica a entrambi i nomi.

Sintassi

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

• $stream — un puntatore a file (una resource) restituito da fopen(). È il file aperto in cui si sta scrivendo, non un nome di file.
• $data — la string da scrivere.
• $length — opzionale. Se specificato, la scrittura si interrompe dopo $length byte, anche se $data è più lunga.

Restituisce il numero di byte scritti, oppure false in caso di errore. Nota che restituisce 0 e non false quando non c'è nulla da scrivere, quindi usa sempre === per confrontare quando controlli gli errori.

Come usare la funzione fputs()

Scrivere in un file segue sempre uno schema in tre passaggi:

1. Apri il file con fopen(), scegliendo una modalità (vedi sotto).
2. Chiama fputs() tutte le volte che serve.
3. Chiudi il file con fclose() per svuotare il buffer e rilasciare l'handle.

<?php

$file = fopen('myfile.txt', 'w');   // open for writing, truncating the file
fputs($file, "Hello, world!\n");    // write a line
fclose($file);                      // flush + release the handle

Dopo l'esecuzione, myfile.txt contiene Hello, world! seguito da un'andata a capo. Il \n è tra virgolette doppie, quindi PHP lo converte in un vero carattere di interruzione di riga (un letterale \n tra virgolette singole verrebbe scritto così com'è).

Scegliere la modalità fopen() corretta

La modalità passata a fopen() determina dove fputs() scrive e se il contenuto esistente viene conservato. Queste sono le modalità che permettono la scrittura:

Usa 'w' per sovrascrivere e 'a' (append) per aggiungere a un log senza perdere ciò che è già presente.

<?php

// Append three lines to a log; each run adds to the end.
$log = fopen('app.log', 'a');
fputs($log, "2026-06-21 user logged in\n");
fputs($log, "2026-06-21 report generated\n");
fclose($log);

Limitare la quantità di dati scritti

Il terzo argomento opzionale limita il numero di byte scritti. È utile quando si vuole scrivere solo un prefisso di una string più lunga:

<?php

$file = fopen('clip.txt', 'w');
$written = fputs($file, 'Hello, world!', 5);  // write only the first 5 bytes
fclose($file);

echo $written;   // 5  — the file now contains "Hello"

$written è 5 e clip.txt contiene solo Hello.

Controllare sempre il valore restituito

Una scrittura può fallire — disco pieno, file in sola lettura o handle chiuso. Poiché fputs() può legittimamente restituire 0, testa il risultato con il confronto rigoroso === false:

<?php

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

if (fputs($file, 'data') === false) {
    echo 'Write failed!';
} else {
    echo 'Write succeeded.';
}

fclose($file);

Questo stampa Write succeeded. ed evita il classico bug in cui if (!fputs(...)) tratta erroneamente una scrittura valida di 0 byte come un errore.

fputs() vs. file_put_contents()

fputs() richiede un handle aperto ed è ideale quando si scrive in modo incrementale (molte scritture piccole, come un ciclo di log). Quando si vuole semplicemente scrivere un'intera string in un file in una sola operazione, file_put_contents() esegue apertura/scrittura/chiusura in una singola chiamata:

<?php

// Equivalent one-liner — no fopen()/fclose() needed.
file_put_contents('myfile.txt', "Hello, world!\n");

Usa fputs()/fwrite() quando hai bisogno di controllo sull'handle (aggiunta di dati in molte chiamate, scritture parziali); usa file_put_contents() per scritture singole e definitive.

Riepilogo

• fputs() è un alias di fwrite() — stesso comportamento, due nomi.
• Scrive in un puntatore a file aperto da fopen(), quindi abbinalo sempre a fclose().
• Restituisce il conteggio dei byte, oppure false in caso di errore — controlla con === false.
• Scegli 'w' per sovrascrivere e 'a' per aggiungere; un parametro length opzionale limita i byte scritti.
• Per una singola scrittura dell'intero file, preferisci file_put_contents(). Per leggere i dati, consulta fgets() e fread().

Pratica