vsprintf()
La fonction vsprintf() en PHP formate une chaîne à partir d'un tableau d'arguments et retourne le résultat sans l'afficher à l'écran.
Introduction
La fonction vsprintf() en PHP formate une chaîne en utilisant un tableau d'arguments et retourne le résultat au lieu de l'afficher. Considérez-la comme la version basée sur un tableau de sprintf() : la chaîne de format et les espaces réservés fonctionnent de manière identique, mais les valeurs proviennent d'un tableau plutôt que d'une liste de paramètres séparés.
Le « v » dans le nom signifie vector (tableau). C'est la fonction à utiliser lorsque vos valeurs se trouvent déjà dans un tableau — par exemple une ligne de base de données, une ligne CSV analysée, ou le résultat de explode() — et que vous ne souhaitez pas les étaler en arguments individuels.
Ce chapitre couvre la syntaxe, les spécificateurs de format les plus courants, des cas de formatage réels (rembourrage, nombres, réorganisation des arguments), et comment vsprintf() diffère des fonctions apparentées de la famille printf/sprintf.
Syntaxe
vsprintf(string $format, array $values): string| Paramètre | Description |
|---|---|
$format | Une chaîne de modèle contenant du texte littéral plus des espaces réservés (également appelés spécificateurs de format) qui commencent par le caractère %. |
$values | Un tableau dont les éléments sont substitués dans les espaces réservés, dans l'ordre. |
La valeur de retour est la chaîne entièrement formatée. Contrairement à vprintf(), rien n'est envoyé vers la sortie — vous décidez de ce que vous faites avec la valeur retournée.
Remarque : Depuis PHP 8.0, passer trop peu de valeurs pour les espaces réservés lève une
ValueError. Dans les versions antérieures, cela déclenchait un avertissement et retournaitfalse.
Premier exemple
Sortie :
I like apple, banana, and orange.Chaque espace réservé %s est remplacé, de gauche à droite, par l'élément suivant de $values. La chaîne finale est retournée et stockée dans $result — elle n'est affichée que parce que nous appelons explicitement echo.
Spécificateurs de format courants
La lettre après % contrôle la façon dont la valeur correspondante est rendue :
| Spécificateur | Signification | Exemple valeur → sortie |
|---|---|---|
%s | String | 'hi' → hi |
%d | Entier signé | 42.9 → 42 |
%f | Nombre flottant | 3.5 → 3.500000 |
%b | Binaire | 5 → 101 |
%x | Hexadécimal minuscule | 255 → ff |
%% | Un signe pourcentage littéral | → % |
Les spécificateurs peuvent également contenir des indicateurs, une largeur et une précision entre le % et la lettre (par exemple %05d ou %.2f), ce qui rend vsprintf() véritablement puissant.
Rembourrage et formatage des nombres
<?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);Sortie :
ID:00042 Price:$42.50 Name:[left ]C'est la raison typique de choisir vsprintf() : vous avez un enregistrement (ici un tableau $row) et un modèle fixe, et vous souhaitez une sortie alignée, complétée par des zéros, au style monétaire sans concaténer des chaînes à la main.
Réutilisation des arguments avec des espaces réservés positionnels
Un espace réservé de la forme %n$ fait référence au n-ième élément du tableau (basé sur 1), vous pouvez donc utiliser la même valeur plusieurs fois ou modifier son ordre indépendamment du tableau :
<?php
$values = ['Sam', 30];
echo vsprintf('%1$s is %2$d years old. Hi %1$s!', $values);Sortie :
Sam is 30 years old. Hi Sam!Ici %1$s est utilisé deux fois, même si 'Sam' n'apparaît qu'une seule fois dans le tableau.
vsprintf() vs. le reste de la famille
Ces quatre fonctions partagent exactement les mêmes règles de chaîne de format ; elles diffèrent uniquement dans la façon dont les arguments sont passés et ce qu'elles font du résultat :
| Fonction | Arguments | Résultat |
|---|---|---|
sprintf() | Paramètres séparés | Retourne la chaîne |
printf() | Paramètres séparés | Affiche et retourne la longueur |
vsprintf() | Un tableau | Retourne la chaîne |
vprintf() | Un tableau | Affiche et retourne la longueur |
La règle générale est donc : utilisez une variante v* lorsque vos données se trouvent déjà dans un tableau, et utilisez les variantes sprintf/vsprintf (sans le print intégré) lorsque vous voulez récupérer la chaîne plutôt qu'une sortie immédiate.
Pièges courants
- Trop peu de valeurs lèvent une erreur. Si le tableau a moins d'éléments que le format a d'espaces réservés, PHP 8+ lève une
ValueError. Assurez-vous que la longueur du tableau correspond au nombre de spécificateurs (non positionnels). - Les valeurs supplémentaires sont ignorées. Avoir plus d'éléments que d'espaces réservés est acceptable — le surplus est silencieusement ignoré.
- Les clés sont ignorées pour les espaces réservés séquentiels.
vsprintf()consomme le tableau par position, non par clé, donc un tableau associatif est lu dans l'ordre d'insertion. - Échappez les signes pourcentage littéraux avec
%%, sinon PHP tente de lire le caractère suivant comme un spécificateur.
Fonctions associées
sprintf()— même formatage avec des arguments séparés.vprintf()— commevsprintf()mais affiche le résultat directement.printf()— affiche une chaîne formatée à partir d'arguments séparés.number_format()— formate les nombres avec des milliers groupés.