fprint()

La funzione PHP fprintf() scrive una stringa formattata in un file aperto (stream). Considerala come printf() — che stampa nel browser/output — ma con la destinazione reindirizzata a un handle di file. È la scelta naturale quando si desidera un testo pulito, allineato e prevedibile in un file di log o in un report generato, invece di costruire stringhe manualmente con la concatenazione.

Questa pagina tratta la sintassi, i specificatori di formato più utilizzati, due esempi completi eseguibili e le funzioni strettamente correlate a cui puoi ricorrere in alternativa.

Sintassi

int fprintf ( resource $handle , string $format [, mixed ...$args ] )

La funzione restituisce il numero di byte scritti, oppure false in caso di errore. Nota che il valore restituito è la lunghezza della stringa scritta, non il numero di argomenti — utile quando è necessario tenere traccia della quantità di dati registrati.

Specificatori di formato

La potenza di fprintf() risiede nella stringa $format. Ogni % introduce un segnaposto:

Gli stessi specificatori funzionano in printf() e sprintf(), quindi una volta appresi qui si applicano ovunque.

Scrittura di un report

Ecco un esempio completo che scrive un piccolo report in un file.

<?php
$file = fopen("report.txt", "w");
if ($file === false) {
    die("Failed to open file");
}
$name = "John";
$age = 30;
$income = 50000;
// \$ prints a literal dollar sign; %.2f rounds the float to 2 decimals
$bytes = fprintf($file, "Name: %s\nAge: %d\nIncome: \$%.2f", $name, $age, $income / 12);
fclose($file);

echo "$bytes bytes written"; // 35 bytes written
?>

Apriamo report.txt in scrittura ("w") e verifichiamo che fopen() non abbia fallito. fprintf() sostituisce quindi ciascuna variabile nella stringa di formato: %s per il nome, %d per l'età e \$%.2f per il reddito mensile (un $ letterale seguito da un float arrotondato a due decimali). Chiama sempre fclose() quando hai finito, in modo che il buffer venga svuotato e l'handle rilasciato.

Il file report.txt risultante contiene:

Name: John
Age: 30
Income: $4166.67

50000 / 12 è 4166.6667, che %.2f arrotonda a 4166.67.

Aggiunta a un file di log

Un utilizzo molto comune è quello di aggiungere una riga formattata a un log. Apri il file in modalità append ("a") in modo che ogni chiamata aggiunga una nuova riga anziché sovrascrivere il contenuto precedente:

<?php
$file = fopen("error.log", "a");
if ($file === false) {
    die("Failed to open file");
}
$error_code = 404;
$date = date("Y-m-d H:i:s");
$ip_address = $_SERVER['REMOTE_ADDR'];
fprintf($file, "[%s] Error %d from IP address %s\n", $date, $error_code, $ip_address);
fclose($file);
?>

Poiché il file viene aperto con "a", ogni esecuzione aggiunge una nuova riga; nulla di ciò che si trova già in error.log viene perso. Il \n alla fine della stringa di formato mette ogni voce su una riga separata. Una tipica riga aggiunta appare così:

[2023-03-15 15:30:00] Error 404 from IP address 192.168.0.1

fprintf() vs. funzioni correlate

Scegliere lo strumento giusto mantiene il codice chiaro:

• printf() — stessa formattazione, ma scrive nell'output standard (browser/CLI) invece che in un file.
• sprintf() — restituisce la stringa formattata invece di scriverla da qualche parte, così puoi memorizzarla o riutilizzarla.
• fwrite() — scrive byte grezzi in un file senza formattazione; usala quando non hai bisogno dei segnaposto %.
• vfprintf() — come fprintf(), ma accetta gli argomenti come un singolo array invece di una lista variadica.

Errori comuni

• Specificatori e argomenti non corrispondenti. %d su una string non numerica produce 0; passare meno argomenti dei segnaposto genera un avviso.
• Dimenticare di eseguire l'escape di %. Per stampare un segno percentuale letterale, usa %%, non %.
• Dimenticare fclose(). I dati bufferizzati potrebbero non essere scaricati su disco fino alla chiusura dell'handle (o al termine dello script).
• La modalità di apertura è importante. "w" tronca il file; "a" aggiunge. Scegli con attenzione.

Pratica