vprintf()

Introduction

La fonction vprintf() en PHP affiche une chaîne formatée. Elle se comporte exactement comme printf(), sauf que les valeurs à substituer sont fournies sous forme d'un seul tableau plutôt que d'arguments séparés. Le v dans le nom signifie vector (tableau).

Cette page couvre la syntaxe, les spécificateurs de format utilisables, un ensemble d'exemples exécutables, les différences avec les fonctions associées, et les erreurs courantes à éviter.

Utilisez vprintf() lorsque les valeurs à formater se trouvent déjà dans un tableau — par exemple, une ligne de base de données, le résultat de explode(), ou une liste construite dynamiquement. Étaler manuellement un tel tableau dans printf($fmt, $row[0], $row[1], ...) est verbeux et se casse dès que le nombre de champs change ; vprintf($fmt, $row) gère n'importe quel nombre d'éléments proprement.

Syntaxe

vprintf(string $format, array $values): int|false

• $format — une chaîne de modèle contenant un ou plusieurs espaces réservés. Chaque espace réservé commence par un signe pourcentage (%) suivi d'un spécificateur de conversion tel que s (string), d (entier) ou f (flottant).
• $values — un tableau dont les éléments remplissent les espaces réservés, dans l'ordre. Il doit contenir au moins autant d'éléments qu'il y a d'espaces réservés.

vprintf() imprime le résultat directement et retourne la longueur de la chaîne de sortie (un int), ou false en cas d'échec. Si vous avez besoin de la chaîne formatée comme valeur plutôt que de l'imprimer, utilisez vsprintf().

Exemple de base

Voici le cas le plus simple — trois espaces réservés de type string remplis à partir d'un tableau :

Cela affichera :

I like apple, banana, and orange.

Chaque %s est remplacé, dans l'ordre, par l'élément suivant de $values.

Spécificateurs de format courants

La chaîne de format est la même que celle utilisée dans toute la famille printf. Les spécificateurs les plus utiles sont :

Vous pouvez également contrôler la largeur, le remplissage, le signe et la précision entre le % et le spécificateur :

<?php

// Pad an integer to 5 digits with leading zeros, show the sign, print binary.
vprintf("%05d / %+d / %b\n", [42, 7, 5]);

// Left-align in 10 columns, then right-align in 10 columns.
vprintf("%-10s|%10s|\n", ["left", "right"]);

// Money: two decimal places.
vprintf("Total: \$%01.2f\n", [49.9]);

Sortie :

00042 / +7 / 101
left      |     right|
Total: $49.90

Réutiliser une valeur avec la numérotation des arguments

Vous pouvez référencer un élément de tableau spécifique plusieurs fois avec la syntaxe d'échange %n$, où n est la position basée sur 1 :

<?php

vprintf("Hex of %1\$d is %1\$x\n", [255]);

Sortie :

Hex of 255 is ff

Ici, %1$d et %1$x lisent tous deux le premier élément du tableau (255) et le formatent respectivement en décimal et en hexadécimal.

Utiliser la valeur de retour

vprintf() retourne le nombre de caractères imprimés, ce qui est utile pour la journalisation ou les vérifications d'alignement :

<?php

$len = vprintf("Total: \$%01.2f\n", [49.9]);
echo "Printed $len characters.\n";

Sortie :

Total: $49.90
Printed 14 characters.

vprintf() vs. fonctions associées

Règle générale : choisissez la version v quand vos données sont dans un tableau, et la version s quand vous souhaitez que la chaîne soit retournée plutôt qu'affichée.

Erreurs courantes

• Comptages non concordants. Si le tableau contient moins d'éléments qu'il n'y a d'espaces réservés, PHP lève une ArgumentCountError (PHP 8+) ou un avertissement sur les versions plus anciennes. Les éléments supplémentaires du tableau sont simplement ignorés.
• Échapper $ dans les guillemets doubles. Un signe dollar littéral avant un chiffre (comme dans $5) peut entrer en conflit avec l'interpolation de variables PHP. Utilisez soit des chaînes de format entre guillemets simples, soit échappez-le avec \$, comme indiqué ci-dessus.
• Oublier qu'elle affiche. vprintf() écrit immédiatement dans la sortie — sa valeur de retour est une longueur, pas la chaîne. Utilisez vsprintf() pour capturer le résultat.
• Tableaux associatifs. Seules les valeurs sont utilisées, dans leur ordre de stockage ; les clés sont ignorées. Passez une liste (tableau numérique et séquentiel) pour éviter les surprises.

Pratique