fprintf()

Introduction

La fonction fprintf() écrit une chaîne formatée dans un flux — un fichier, php://stdout, php://stderr, ou toute autre ressource de flux ouverte — et remplit ses espaces réservés à partir d'une liste d'arguments séparés. Le f du nom signifie file : contrairement à printf(), qui affiche directement vers la sortie, fprintf() envoie son résultat vers un flux de votre choix.

C'est le membre de la famille printf dédié à l'écriture dans un flux. Comparée à vfprintf(), elle effectue exactement le même travail, mais les deux fonctions reçoivent leurs valeurs différemment : fprintf() prend chaque valeur comme argument séparé, tandis que vfprintf() prend un seul tableau. Optez pour fprintf() lorsque vous avez quelques valeurs distinctes à écrire dans un fichier ou une console.

Ce chapitre couvre la syntaxe, les spécificateurs de format, des exemples exécutables, la comparaison avec les fonctions apparentées, et les pièges courants.

Syntaxe

fprintf(resource $stream, string $format, mixed ...$values): int

Elle retourne le nombre de caractères écrits. Sur les versions récentes de PHP, un appel mal formé génère une erreur plutôt que de retourner false, donc vous avez rarement besoin de tester 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 :

Entre le % et la lettre de type, vous pouvez ajouter la largeur, le rembourrage et la précision — 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

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

<?php

$out = fopen("php://stdout", "w");

fprintf($out, "Name: %s | Age: %d | Balance: %.2f\n", "John", 30, 1234.5);

fclose($out);

Résultat :

Name: John | Age: 30 | Balance: 1234.50

Les trois arguments 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 classique consiste à écrire des lignes formatées et alignées dans un fichier — par exemple un petit journal :

<?php

$log = fopen("app.log", "a");

fprintf($log, "[%s] %-5s %s\n", "2026-07-02", "INFO", "Server started");
fprintf($log, "[%s] %-5s %s\n", "2026-07-02", "ERROR", "Disk full");

fclose($log);

echo file_get_contents("app.log");

Résultat :

[2026-07-02] INFO  Server started
[2026-07-02] ERROR Disk full

%-5s aligne le niveau à gauche dans une colonne de 5 caractères, de sorte que les messages commencent à la même position, que le niveau soit INFO ou ERROR. Ouvrir le fichier avec le mode "a" (ajout) ajoute chaque ligne sans tronquer ce qui existe déjà. Chaque appel à fprintf() écrit une ligne, en prenant ses valeurs comme arguments séparés.

fprintf() vs printf() vs vfprintf()

Ces trois fonctions partagent exactement les mêmes règles de chaîne de format et ne diffèrent que par où le résultat est envoyé et comment les valeurs sont passées :

Ainsi, fprintf() est printf() qui écrit dans un flux au lieu de la sortie, et c'est vfprintf() avec des arguments séparés au lieu d'un tableau :

// Arguments séparés → écrits dans $stream
fprintf($stream, "%s is %d", $name, $age);

// Les mêmes valeurs sous forme de tableau → écrites dans $stream
vfprintf($stream, "%s is %d", [$name, $age]);

Si vous souhaitez simplement récupérer la chaîne formatée sans l'écrire nulle part, utilisez sprintf(). Un idiome courant de fprintf() dans les scripts en ligne de commande consiste à écrire les diagnostics vers le flux d'erreur, en les gardant séparés de la sortie normale :

<?php

fprintf(STDERR, "Error: %s (code %d)\n", "connection refused", 111);

STDERR est une constante de flux prédéfinie disponible pour les scripts PHP en CLI, vous n'avez donc pas besoin de l'ouvrir avec fopen() au préalable.

Pièges courants

• Le flux vient en premier. La ressource de flux est le premier argument ; la chaîne de format est le second. Passer le format en premier (comme avec printf()) est l'erreur la plus fréquente lorsqu'on passe de l'une à l'autre.
• Le flux doit être accessible en écriture. Ouvrir un fichier avec "r" (mode lecture) et le passer à fprintf() échoue — utilisez un mode d'écriture tel que "w" (tronquer) ou "a" (ajouter).
• Elle écrit, elle ne retourne pas de texte. La valeur de retour est le nombre de caractères, pas la chaîne formatée — une confusion fréquente avec sprintf().
• Trop peu d'arguments génèrent une erreur. Fournir moins de valeurs que le format ne compte de spécificateurs déclenche une ArgumentCountError sur PHP 8+ ; les valeurs en trop sont simplement ignorées.
• Échappez les signes pourcentage littéraux avec %%, sinon PHP tente de lire le caractère suivant comme un spécificateur.

Conclusion

fprintf() formate une chaîne et l'écrit dans un flux, en prenant ses valeurs comme arguments séparés. C'est l'outil de choix lorsque vous voulez une sortie précise et en colonnes envoyée vers un fichier ou vers la console — lignes de journal, rapports, ou diagnostics CLI sur php://stderr. Pour les variantes apparentées, voir printf() (affiche vers la sortie), sprintf() (retourne une chaîne), et vfprintf() (même destination, mais prend un tableau de valeurs).

Pratique