fprintf()

Introduzione

La funzione fprintf() scrive una stringa formattata su uno stream — un file, php://stdout, php://stderr, o qualsiasi altra risorsa stream aperta — e riempie i suoi segnaposto a partire da un elenco di argomenti separati. La f nel nome sta per file: a differenza di printf(), che stampa direttamente sull'output, fprintf() invia il suo risultato a uno stream scelto da te.

È il membro della famiglia printf dedicato alla scrittura su stream. Rispetto a vfprintf(), le due funzioni svolgono esattamente lo stesso compito ma ricevono i valori in modo diverso: fprintf() prende ogni valore come argomento a sé, mentre vfprintf() prende un unico array. Scegli fprintf() quando hai alcuni valori separati da scrivere su un file o sulla console.

Questo capitolo tratta la sintassi, gli specificatori di formato, esempi eseguibili, il confronto con le funzioni correlate e gli errori comuni.

Sintassi

fprintf(resource $stream, string $format, mixed ...$values): int

Restituisce il numero di caratteri scritti. Nel PHP moderno, una chiamata malformata genera un errore anziché restituire false, quindi raramente è necessario testare il valore di ritorno per rilevare un fallimento.

Specificatori di formato

La stringa $format mescola testo letterale con segnaposto che iniziano con %. Gli specificatori più comuni sono:

Tra il % e la lettera di tipo puoi aggiungere larghezza, riempimento e precisione — ad esempio %05d (riempie un intero fino a 5 cifre con zeri) o %.2f (due cifre decimali). Un % letterale deve essere scritto come %%.

Esempio: scrittura sull'output standard

Aprendo lo stream php://stdout puoi vedere il risultato immediatamente, il che rende fprintf() facile da provare:

<?php

$out = fopen("php://stdout", "w");

fprintf($out, "Name: %s | Age: %d | Balance: %.2f\n", "John", 30, 1234.5);

fclose($out);

Output:

Name: John | Age: 30 | Balance: 1234.50

I tre argomenti riempiono %s, %d e %.2f nell'ordine: la stringa viene stampata così com'è, %d elimina la parte decimale di un intero e %.2f formatta il float con esattamente due cifre decimali.

Esempio: scrittura su file

Il caso d'uso classico è la scrittura di righe formattate e allineate su un file — ad esempio un piccolo log:

<?php

$log = fopen("app.log", "a");

fprintf($log, "[%s] %-5s %s\n", "2026-07-02", "INFO", "Server started");
fprintf($log, "[%s] %-5s %s\n", "2026-07-02", "ERROR", "Disk full");

fclose($log);

echo file_get_contents("app.log");

Output:

[2026-07-02] INFO  Server started
[2026-07-02] ERROR Disk full

%-5s allinea a sinistra il livello in una colonna di 5 caratteri, così i messaggi iniziano sempre nella stessa posizione, indipendentemente dal fatto che il livello sia INFO o ERROR. Aprire il file con la modalità "a" (append) aggiunge ogni riga senza troncare ciò che è già presente. Ogni chiamata a fprintf() scrive una riga, prendendo i suoi valori come argomenti separati.

fprintf() vs printf() vs vfprintf()

Queste tre funzioni condividono esattamente le stesse regole della stringa di formato e differiscono solo per dove va il risultato e come vengono passati i valori:

Quindi fprintf() è printf() che scrive su uno stream invece che sull'output, ed è vfprintf() con argomenti separati invece di un array:

// Argomenti separati → scritti su $stream
fprintf($stream, "%s is %d", $name, $age);

// Gli stessi valori come array → scritti su $stream
vfprintf($stream, "%s is %d", [$name, $age]);

Se vuoi solo la stringa formattata restituita, invece di scriverla da qualche parte, usa sprintf(). Un idioma comune di fprintf() negli script da riga di comando è scrivere le informazioni diagnostiche sullo stream di errore, tenendole separate dall'output normale:

<?php

fprintf(STDERR, "Error: %s (code %d)\n", "connection refused", 111);

STDERR è una costante di stream predefinita disponibile negli script PHP CLI, quindi non è necessario aprirla prima con fopen().

Errori comuni

• Lo stream viene prima. La risorsa stream è il primo argomento; la stringa di formato è il secondo. Passare prima la stringa di formato (come con printf()) è l'errore più comune quando si passa da una funzione all'altra.
• Lo stream deve essere scrivibile. Aprire un file con "r" (modalità lettura) e passarlo a fprintf() fallisce — usa una modalità scrivibile come "w" (tronca) o "a" (append).
• Scrive, non restituisce testo. Il valore di ritorno è il conteggio dei caratteri, non la stringa formattata — una confusione frequente con sprintf().
• Troppo pochi argomenti generano un errore. Fornire meno valori rispetto agli specificatori presenti nel formato genera un ArgumentCountError su PHP 8+; i valori in eccesso vengono semplicemente ignorati.
• Fai l'escape dei simboli di percentuale letterali come %%, altrimenti PHP tenta di leggere il carattere successivo come uno specificatore.

Conclusione

fprintf() formatta una stringa e la scrive su uno stream, prendendo i valori come argomenti separati. È lo strumento da scegliere quando vuoi un output preciso e in colonne inviato a un file o alla console — righe di log, report o diagnostica CLI su php://stderr. Per le varianti correlate, vedi printf() (stampa sull'output), sprintf() (restituisce una stringa) e vfprintf() (stessa destinazione, ma prende un array di valori).

Esercizio