fprint()

La fonction PHP fprintf() écrit une chaîne formatée dans un fichier ouvert (flux). Considérez-la comme printf() — qui affiche dans le navigateur/la sortie — mais avec la destination redirigée vers un descripteur de fichier. C'est le choix naturel lorsque vous souhaitez un texte propre, aligné et prévisible dans un fichier journal ou un rapport généré, plutôt que de construire des chaînes manuellement par concaténation.

Cette page couvre la syntaxe, les spécificateurs de format les plus couramment utilisés, deux exemples complets exécutables, et les fonctions étroitement liées que vous pouvez utiliser à la place.

Syntaxe

int fprintf ( resource $handle , string $format [, mixed ...$args ] )

La fonction retourne le nombre d'octets écrits, ou false en cas d'échec. Notez que la valeur de retour correspond à la longueur de la chaîne écrite, et non au nombre d'arguments — utile lorsque vous devez suivre la quantité de données journalisées.

Spécificateurs de format

La puissance de fprintf() réside dans la chaîne $format. Chaque % introduit un espace réservé :

Les mêmes spécificateurs fonctionnent dans printf() et sprintf(), donc une fois appris ici, ils s'appliquent partout.

Écriture d'un rapport

Voici un exemple complet qui écrit un petit rapport dans un fichier.

<?php
$file = fopen("report.txt", "w");
if ($file === false) {
    die("Failed to open file");
}
$name = "John";
$age = 30;
$income = 50000;
// \$ prints a literal dollar sign; %.2f rounds the float to 2 decimals
$bytes = fprintf($file, "Name: %s\nAge: %d\nIncome: \$%.2f", $name, $age, $income / 12);
fclose($file);

echo "$bytes bytes written"; // 35 bytes written
?>

Nous ouvrons report.txt en écriture ("w") et vérifions que fopen() n'a pas échoué. fprintf() substitue ensuite chaque variable dans la chaîne de format : %s pour le nom, %d pour l'âge, et \$%.2f pour le revenu mensuel (un $ littéral suivi d'un flottant arrondi à deux décimales). Appelez toujours fclose() lorsque vous avez terminé afin de vider le tampon et de libérer le descripteur.

Le fichier report.txt résultant contient :

Name: John
Age: 30
Income: $4166.67

50000 / 12 vaut 4166.6667, que %.2f arrondit à 4166.67.

Ajout dans un fichier journal

Une utilisation très courante consiste à ajouter une ligne formatée dans un journal. Ouvrez le fichier en mode ajout ("a") afin que chaque appel ajoute une nouvelle ligne au lieu d'écraser le contenu existant :

<?php
$file = fopen("error.log", "a");
if ($file === false) {
    die("Failed to open file");
}
$error_code = 404;
$date = date("Y-m-d H:i:s");
$ip_address = $_SERVER['REMOTE_ADDR'];
fprintf($file, "[%s] Error %d from IP address %s\n", $date, $error_code, $ip_address);
fclose($file);
?>

Le fichier étant ouvert avec "a", chaque exécution ajoute une nouvelle ligne ; rien de ce qui se trouve déjà dans error.log n'est perdu. Le \n à la fin de la chaîne de format place chaque entrée sur sa propre ligne. Une ligne typique ajoutée ressemble à :

[2023-03-15 15:30:00] Error 404 from IP address 192.168.0.1

fprintf() vs. fonctions connexes

Choisir le bon outil maintient votre code clair :

• printf() — même formatage, mais écrit vers la sortie standard (navigateur/CLI) plutôt que dans un fichier.
• sprintf() — retourne la chaîne formatée au lieu de l'écrire où que ce soit, afin de pouvoir la stocker ou la réutiliser.
• fwrite() — écrit des octets bruts dans un fichier sans formatage ; utilisez-la quand vous n'avez pas besoin d'espaces réservés %.
• vfprintf() — comme fprintf(), mais prend les arguments sous forme d'un seul array au lieu d'une liste variadique.

Pièges courants

• Spécificateurs et arguments non correspondants. %d appliqué à une string non numérique donne 0 ; passer moins d'arguments que d'espaces réservés déclenche un avertissement.
• Oublier d'échapper %. Pour afficher un signe pourcentage littéral, utilisez %%, et non %.
• Oublier fclose(). Les données en mémoire tampon peuvent ne pas être écrites sur le disque tant que le descripteur n'est pas fermé (ou que le script ne se termine pas).
• Le mode d'ouverture est important. "w" tronque le fichier ; "a" ajoute. Choisissez délibérément.

Pratique