Fonction vsprintf() PHP : Formatage de chaînes avec tableau d'arguments

Disponible depuis : PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8

Définition et utilisation de vsprintf()

La fonction vsprintf() retourne une chaîne formatée en remplaçant les spécificateurs de format (%s, %d, %f…) par les valeurs d'un tableau d'arguments. Contrairement à sprintf() qui accepte des arguments individuels, vsprintf() reçoit un tableau, ce qui la rend idéale pour les situations où les données sont déjà regroupées dans un tableau — par exemple lors de la récupération de données depuis une base de données ou une API REST.

Le traitement est séquentiel et positionnel : le premier % est remplacé par le premier élément du tableau, le deuxième % par le deuxième élément, et ainsi de suite. Il est également possible de réutiliser un même argument grâce aux spécificateurs positionnels (%1$s, %2$d…), une fonctionnalité particulièrement utile pour l'internationalisation des applications.

Cas d'usage typiques : génération de messages dynamiques localisés, construction de requêtes formatées, création de rapports automatisés, formatage de sorties CLI en PHP.

Syntaxe

vsprintf(string $format, array $values): string

Note importante sur les spécificateurs positionnels : Si vous devez utiliser une même valeur du tableau plusieurs fois, ou si vous souhaitez changer l'ordre d'insertion sans modifier le tableau, utilisez la notation %n$ où n est la position (base 1) dans le tableau. Voir l'exemple 3 ci-dessous.

Exemple 1 — Insertion de chaîne et d'entier non signé

Cet exemple illustre l'usage le plus courant de vsprintf() : remplacer un spécificateur de chaîne (%s) et un spécificateur entier non signé (%u) par les valeurs du tableau. La chaîne formatée est stockée dans une variable avant d'être affichée, ce qui permet de la réutiliser ou de la manipuler ultérieurement.

<?php
// Déclaration des variables à insérer dans la chaîne formatée
$chaine = "Bonjour";
$number = 123;
// vsprintf() retourne la chaîne formatée (ne l'affiche pas)
// %s sera remplacé par $chaine, %u par $number
$txt = vsprintf("%s le monde. Jour numéro %u", array($chaine, $number));
// Affichage du résultat
echo $txt;
?>

Résultat :

Bonjour le monde. Jour numéro 123

Exemple 2 — Formatage de nombres flottants avec précision

Cet exemple montre le formatage de nombres décimaux avec %f (nombre à virgule flottante). Sans précision spécifiée, PHP affiche 6 décimales par défaut. Notez que les deux nombres sont concaténés directement sans séparateur dans la chaîne de format — pensez à ajouter un espace ou un séparateur selon vos besoins.

<?php
// Deux nombres entiers qui seront formatés comme flottants
$num1 = 123;
$num2 = 456;
// %f affiche chaque nombre avec 6 décimales par défaut
// Ici pas de séparateur entre les deux valeurs dans le format
$txt = vsprintf("%f %f", array($num1, $num2));
echo $txt;
// Pour limiter à 2 décimales, utiliser %.2f à la place de %f
$txt2 = vsprintf("%.2f et %.2f", array($num1, $num2));
echo "<br>" . $txt2;
?>

Résultat :

123.000000 456.000000
123.00 et 456.00

Exemple 3 — Spécificateurs positionnels pour réutiliser un argument

Les spécificateurs positionnels (%1$, %2$…) permettent d'accéder directement à un élément précis du tableau par sa position. Cela est particulièrement utile lorsqu'on doit afficher une même valeur plusieurs fois avec des formats différents, ou réorganiser l'ordre d'affichage sans modifier le tableau source — un atout majeur pour l'internationalisation (i18n) des applications PHP.

<?php
// Un seul nombre utilisé deux fois avec des formats différents
$number = 123;
// %1$ fait référence au 1er élément du tableau (index 0)
// .2f : affichage en flottant avec 2 décimales
// u   : affichage en entier non signé (sans décimales)
$txt = vsprintf(
    "Avec 2 décimales : %1\$.2f<br>Sans décimales : %1\$u",
    array($number)
);
echo $txt;
?>

Résultat :

Avec 2 décimales : 123.00
Sans décimales : 123

Exemple 4 — Alignement et remplissage pour formatage tabulaire

vsprintf() excelle dans la génération de sorties tabulaires alignées, notamment pour les interfaces CLI ou les rapports texte. Cet exemple illustre l'utilisation des modificateurs de largeur et de caractère de remplissage pour aligner des données en colonnes.

<?php
// Données produits : nom et prix
$produits = [
    ["Clavier mécanique", 89.9],
    ["Souris ergonomique", 45.0],
    ["Écran 4K", 399.99],
];
echo "<pre>";
foreach ($produits as $item) {
    // %-20s : chaîne alignée à gauche dans 20 caractères
    // %8.2f : flottant aligné à droite dans 8 caractères, 2 décimales
    echo vsprintf("%-20s %8.2f €\n", $item);
}
echo "</pre>";
?>

Résultat :

Clavier mécanique    89.90 €
Souris ergonomique   45.00 €
Écran 4K            399.99 €

vsprintf() vs sprintf() vs printf() : quelle fonction choisir ?

Ces trois fonctions partagent le même moteur de formatage mais diffèrent par leur interface et leur sortie :

• sprintf(format, arg1, arg2…) — Arguments individuels, retourne une chaîne. Idéal quand le nombre d'arguments est connu et fixe.
• vsprintf(format, array) — Arguments en tableau, retourne une chaîne. Idéal quand les données sont déjà dans un tableau (BDD, API).
• printf(format, arg1…) — Arguments individuels, affiche directement. Utiliser quand on n'a pas besoin de stocker le résultat.
• vprintf(format, array) — Arguments en tableau, affiche directement. Équivalent de vsprintf() + echo.

Par carabde | Créé le 22 août 2014 | Mis à jour le 18 février 2026