vsprintf()
La funzione vsprintf() in PHP formatta una stringa usando un array di argomenti e restituisce il risultato invece di stamparlo a schermo.
Introduzione
La funzione vsprintf() in PHP formatta una stringa usando un array di argomenti e restituisce il risultato invece di stamparlo. Può essere considerata come la versione basata su array di sprintf(): la stringa di formato e i segnaposto funzionano in modo identico, ma i valori provengono da un unico array anziché da una lista di parametri separati.
La "v" nel nome sta per vector (array). Questa è la funzione da usare quando i valori si trovano già in un array — ad esempio una riga di database, una riga CSV analizzata, o il risultato di explode() — e non si vogliono distribuire in argomenti individuali.
Questo capitolo tratta la sintassi, i specificatori di formato più comuni, casi di formattazione reali (padding, numeri, riordinamento degli argomenti), e come vsprintf() differisce dalla famiglia correlata printf/sprintf.
Sintassi
vsprintf(string $format, array $values): string| Parametro | Descrizione |
|---|---|
$format | Una stringa modello contenente testo letterale più segnaposto (detti anche specificatori di formato) che iniziano con il carattere %. |
$values | Un array i cui elementi vengono sostituiti nei segnaposto, in ordine. |
Il valore di ritorno è la stringa completamente formattata. A differenza di vprintf(), nulla viene inviato all'output — sei tu a decidere cosa fare con il valore restituito.
Nota: A partire da PHP 8.0, passare troppo pochi valori per i segnaposto lancia un
ValueError. Nelle versioni precedenti veniva generato un avviso e veniva restituitofalse.
Un primo esempio
Output:
I like apple, banana, and orange.Ogni segnaposto %s viene sostituito, da sinistra a destra, con l'elemento successivo di $values. La stringa finita viene restituita e memorizzata in $result — viene stampata solo perché chiamiamo esplicitamente echo.
Specificatori di formato comuni
La lettera dopo % controlla come viene reso il valore corrispondente:
| Specificatore | Significato | Valore di esempio → output |
|---|---|---|
%s | String | 'hi' → hi |
%d | Intero con segno | 42.9 → 42 |
%f | Virgola mobile | 3.5 → 3.500000 |
%b | Binario | 5 → 101 |
%x | Esadecimale minuscolo | 255 → ff |
%% | Un simbolo di percentuale letterale | → % |
Gli specificatori possono anche avere flag, una larghezza e una precisione tra il % e la lettera (ad esempio %05d o %.2f), ed è qui che vsprintf() diventa davvero potente.
Padding e formattazione dei numeri
<?php
// %05d → pad the integer with zeros to a width of 5
// %01.2f → at least 1 digit, exactly 2 decimal places
// %-10s → left-align the string in a 10-char field
$row = [42, 42.5, 'left'];
echo vsprintf("ID:%05d Price:\$%01.2f Name:[%-10s]", $row);Output:
ID:00042 Price:$42.50 Name:[left ]Questo è il motivo tipico per scegliere vsprintf(): hai un record (qui un array $row) e un template fisso, e vuoi un output allineato, con zero-padding, in stile valuta senza concatenare stringhe a mano.
Riutilizzo degli argomenti con segnaposto posizionali
Un segnaposto della forma %n$ fa riferimento all'n-esimo elemento dell'array (base 1), quindi puoi usare lo stesso valore più di una volta o cambiare il suo ordine indipendentemente dall'array:
<?php
$values = ['Sam', 30];
echo vsprintf('%1$s is %2$d years old. Hi %1$s!', $values);Output:
Sam is 30 years old. Hi Sam!Qui %1$s viene usato due volte, anche se 'Sam' appare una sola volta nell'array.
vsprintf() rispetto al resto della famiglia
Queste quattro funzioni condividono esattamente le stesse regole per la stringa di formato; differiscono solo nel modo in cui vengono passati gli argomenti e cosa fanno con il risultato:
| Funzione | Argomenti | Risultato |
|---|---|---|
sprintf() | Parametri separati | Restituisce la stringa |
printf() | Parametri separati | Stampa e restituisce la lunghezza |
vsprintf() | Un array | Restituisce la stringa |
vprintf() | Un array | Stampa e restituisce la lunghezza |
La regola pratica è quindi: usa una variante v* quando i tuoi dati si trovano già in un array, e usa le varianti sprintf/vsprintf (senza print interno) quando vuoi ottenere la stringa invece di un output immediato.
Errori comuni
- Troppo pochi valori generano un errore. Se l'array ha meno elementi dei segnaposto nel formato, PHP 8+ lancia un
ValueError. Assicurati che la lunghezza dell'array corrisponda al numero di specificatori (non posizionali). - I valori in eccesso vengono ignorati. Avere più elementi che segnaposto va bene — il surplus viene silenziosamente scartato.
- Le chiavi vengono ignorate per i segnaposto sequenziali.
vsprintf()consuma l'array per posizione, non per chiave, quindi un array associativo viene letto nell'ordine di inserimento. - Escape dei simboli di percentuale letterali come
%%, altrimenti PHP tenta di leggere il carattere successivo come specificatore.
Funzioni correlate
sprintf()— stessa formattazione con argomenti separati.vprintf()— comevsprintf()ma stampa il risultato direttamente.printf()— stampa una stringa formattata da argomenti separati.number_format()— formatta i numeri con raggruppamento delle migliaia.