vfprintf()

Introduzione

La funzione vfprintf() scrive una stringa formattata su uno stream — come un file o l'output standard — e prende i suoi valori da un array invece che da un elenco di argomenti separati. La v iniziale sta per vector (un array di argomenti); la f sta per file (scrive su uno stream).

In sintesi, vfprintf() sta a fprintf() come vsprintf() sta a sprintf(): esegue la stessa formattazione, ma riceve un unico array anziché ogni argomento separatamente. È la funzione da usare quando i valori sono già raccolti in un array.

Questo capitolo tratta la sintassi, gli specificatori di formato, esempi eseguibili, quando preferirla rispetto alle alternative e gli errori comuni.

Sintassi

vfprintf(resource $stream, string $format, array $values): int

Restituisce il numero di caratteri scritti. Nella maggior parte delle versioni PHP, una chiamata malformata genera un errore anziché restituire false, quindi di norma non si testa il valore di ritorno per rilevare errori.

Specificatori di formato

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

È possibile aggiungere larghezza, riempimento e precisione tra il % e la lettera di tipo — 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

Usando lo stream php://stdout è possibile vedere il risultato immediatamente, rendendo vfprintf() facile da provare:

<?php

$out    = fopen("php://stdout", "w");
$values = ["John", 30, 1234.5];

vfprintf($out, "Name: %s | Age: %d | Balance: %.2f\n", $values);

fclose($out);

Output:

Name: John | Age: 30 | Balance: 1234.50

I tre elementi dell'array 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 originale è la scrittura di righe formattate su un file. Qui aggiungiamo tre righe prese da un array di record:

<?php

$records = [
    ["Alice", 95],
    ["Bob",   82],
    ["Carol", 77],
];

$file = fopen("scores.txt", "w");

foreach ($records as $row) {
    vfprintf($file, "%-10s %3d%%\n", $row);
}

fclose($file);

echo file_get_contents("scores.txt");

Output:

Alice       95%
Bob         82%
Carol       77%

%-10s allinea a sinistra il nome in una colonna di 10 caratteri, %3d allinea a destra il punteggio in una colonna di 3 caratteri e %% stampa il simbolo di percentuale letterale. Poiché ogni $row è già un array, vfprintf() lo consuma direttamente — senza bisogno di estrarre i valori.

Perché usare un array? vfprintf() vs fprintf()

fprintf() riceve i suoi valori come argomenti separati:

fprintf($file, "%s is %d", $name, $age);

vfprintf() riceve gli stessi valori in un unico array:

vfprintf($file, "%s is %d", [$name, $age]);

Preferire vfprintf() quando i valori sono già in un array — ad esempio una riga di database, una riga CSV analizzata o argomenti costruiti in un ciclo — così non è necessario estrarli con l'operatore spread (...$row). Se si vuole semplicemente la stringa formattata anziché scriverla su uno stream, usare vsprintf(); per stampare direttamente sull'output senza una risorsa stream, usare vprintf().

Errori comuni

• L'array deve avere almeno tanti elementi quanti sono gli specificatori. Valori insufficienti provocano un ArgumentCountError (PHP 8+); i valori in eccesso vengono semplicemente ignorati.
• L'ordine è importante. Gli elementi vengono consumati in modo posizionale, nell'ordine dell'array. Per fare riferimento a un elemento specifico indipendentemente dall'ordine, usare segnaposto numerati come %1$s e %2$d.
• Scrive, non restituisce testo. Il valore di ritorno è un conteggio di caratteri, non la stringa formattata — è una confusione frequente con vsprintf().
• Lo stream deve essere scrivibile. Aprire un file con "r" (modalità lettura) e passarlo a vfprintf() fallisce.

Conclusione

vfprintf() formatta una stringa e la scrive su uno stream, prendendo i valori da un array. È ideale quando i dati sono già raccolti in un array e si vuole scriverli su un file o sull'output standard in un formato preciso e colonnare. Per le varianti senza stream, vedere vsprintf() (restituisce una stringa) e vprintf() (stampa direttamente), e confrontare con fprintf() quando gli argomenti sono valori separati anziché un array.

Esercizio