vfprintf()

Introduction

La fonction vfprintf() écrit une chaîne formatée dans un flux — comme un fichier ou la sortie standard — et prend ses valeurs depuis un tableau plutôt qu'une liste d'arguments séparés. Le v initial signifie vector (un tableau d'arguments) ; le f signifie file (elle cible un flux).

En bref, vfprintf() est à fprintf() ce que vsprintf() est à sprintf() : elle effectue le même formatage, mais vous lui passez un seul tableau plutôt que d'énumérer chaque argument. C'est la fonction à privilégier lorsque les valeurs sont déjà regroupées dans un tableau.

Ce chapitre couvre la syntaxe, les spécificateurs de format, des exemples exécutables, les cas où la préférer aux alternatives, et les pièges courants.

Syntaxe

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

Elle retourne le nombre de caractères écrits. Dans la plupart des versions de PHP, un appel mal formé génère une erreur plutôt que de retourner false, donc vous ne testez pas normalement la valeur de retour pour détecter un échec.

Spécificateurs de format

La chaîne $format mélange du texte littéral avec des espaces réservés commençant par %. Les spécificateurs les plus courants sont :

Vous pouvez ajouter la largeur, le rembourrage et la précision entre le % et la lettre de type — par exemple %05d (rembourrer un entier sur 5 chiffres avec des zéros) ou %.2f (deux décimales). Un % littéral doit être écrit %%.

Exemple : écriture vers la sortie standard

Utiliser le flux php://stdout permet de voir le résultat immédiatement, ce qui rend vfprintf() facile à tester :

<?php

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

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

fclose($out);

Résultat :

Name: John | Age: 30 | Balance: 1234.50

Les trois éléments du tableau remplissent %s, %d et %.2f dans l'ordre : la chaîne est imprimée telle quelle, %d supprime la partie décimale d'un entier, et %.2f formate le flottant avec exactement deux décimales.

Exemple : écriture dans un fichier

Le cas d'utilisation original consiste à écrire des lignes formatées dans un fichier. Ici, nous ajoutons trois lignes issues d'un tableau d'enregistrements :

<?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");

Résultat :

Alice       95%
Bob         82%
Carol       77%

%-10s aligne le nom à gauche dans une colonne de 10 caractères, %3d aligne le score à droite dans une colonne de 3 caractères, et %% imprime le signe pourcentage littéral. Comme chaque $row est déjà un tableau, vfprintf() le consomme directement — pas besoin de décompresser les valeurs.

Pourquoi utiliser un tableau ? vfprintf() vs fprintf()

fprintf() prend ses valeurs comme arguments séparés :

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

vfprintf() prend les mêmes valeurs dans un seul tableau :

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

Préférez vfprintf() lorsque les valeurs sont déjà dans un tableau — par exemple une ligne de base de données, une ligne CSV analysée, ou des arguments accumulés dans une boucle — afin de ne pas avoir à les décompresser avec l'opérateur de décomposition (...$row). Si vous souhaitez simplement récupérer la chaîne formatée plutôt que de l'écrire dans un flux, utilisez vsprintf() ; pour afficher directement vers la sortie sans ressource de flux, utilisez vprintf().

Pièges courants

• Le tableau doit avoir au moins autant d'éléments que de spécificateurs. Trop peu de valeurs déclenche une ArgumentCountError (PHP 8+) ; les valeurs supplémentaires sont simplement ignorées.
• L'ordre est important. Les éléments sont consommés positionnellement, dans l'ordre du tableau. Pour référencer un élément spécifique quel que soit l'ordre, utilisez des espaces réservés numérotés comme %1$s et %2$d.
• Elle écrit, elle ne retourne pas de texte. La valeur de retour est un nombre de caractères, pas la chaîne formatée — une confusion fréquente avec vsprintf().
• Le flux doit être accessible en écriture. Ouvrir un fichier avec "r" (mode lecture) et le passer à vfprintf() échoue.

Conclusion

vfprintf() formate une chaîne et l'écrit dans un flux, en prenant ses valeurs depuis un tableau. Elle excelle lorsque vos données sont déjà collectées dans un tableau et que vous souhaitez les écrire dans un fichier ou vers la sortie standard dans un format précis en colonnes. Pour les variantes sans flux, voir vsprintf() (retourne une chaîne) et vprintf() (affiche directement), et comparez avec fprintf() lorsque vos arguments sont des valeurs séparées plutôt qu'un tableau.

Pratique