fwrite()

Qu'est-ce que la fonction fwrite() ?

fwrite() est une fonction PHP intégrée qui écrit une string dans un fichier ouvert. Elle écrit à partir de la position actuelle du pointeur de fichier et avance ce pointeur du nombre d'octets écrits, de sorte que des appels consécutifs s'ajoutent les uns aux autres plutôt que d'écraser le contenu. C'est la méthode standard de bas niveau pour écrire dans des fichiers en PHP, et elle est également couramment aliasée comme fputs() (les deux sont identiques).

Cette page couvre la syntaxe, l'argument optionnel length, les modes de fichier qui contrôlent où et comment les données sont écrites, les valeurs de retour, la gestion des erreurs, et les tâches courantes pour lesquelles vous utiliserez fwrite().

Syntaxe

fwrite(resource $stream, string $data, ?int $length = null): int|false

Valeur de retour : le nombre d'octets réellement écrits, ou false en cas d'échec. Étant donné qu'une écriture partielle (moins d'octets que strlen($data)) est possible sur certains flux, un code robuste vérifie la valeur de retour plutôt que de supposer le succès.

Vous n'avez presque jamais besoin de l'argument length. fwrite($file, $data) écrit déjà toute la string. Ne passez une longueur que lorsque vous souhaitez délibérément tronquer la sortie aux N premiers octets.

Un exemple de base

<?php

$filename = 'myfile.txt';
$file = fopen($filename, 'w');     // open for writing (truncates the file)

if ($file === false) {
    exit("Could not open $filename for writing");
}

$bytes = fwrite($file, "Hello, world!");
fclose($file);

echo "Wrote $bytes bytes."; // Wrote 13 bytes.

Trois étapes sont toujours impliquées :

1. Ouvrir le fichier avec fopen() dans un mode qui autorise l'écriture.
2. Appeler fwrite() une ou plusieurs fois pour envoyer des données dans le flux.
3. Fermer le fichier avec fclose() pour vider le tampon et libérer le descripteur.

"Hello, world!" fait 13 caractères, donc fwrite() retourne 13.

Modes de fichier : où vont les octets

Le comportement de fwrite() est décidé presque entièrement par le mode que vous avez passé à fopen(). C'est la source de confusion la plus courante, il vaut donc la peine de le mémoriser :

Si votre fichier finit toujours vide ou perd les données de la veille, vous avez presque certainement ouvert avec 'w' alors que vous vouliez 'a'.

Ajouter plutôt qu'écraser

<?php

$log = fopen('app.log', 'a');           // 'a' keeps existing lines
fwrite($log, "User logged in\n");       // \n adds a newline
fwrite($log, "Order placed\n");
fclose($log);

Chaque exécution de ce script ajoute deux lignes supplémentaires à app.log au lieu de l'effacer.

Écrire plusieurs lignes

fwrite() écrit exactement les octets que vous lui fournissez — il n'ajoute pas de sauts de ligne. Incluez \n vous-même (entre guillemets doubles, pour que l'échappement soit interprété) :

<?php

$file = fopen('names.txt', 'w');

$names = ['Alice', 'Bob', 'Carol'];
foreach ($names as $name) {
    fwrite($file, $name . PHP_EOL); // PHP_EOL = OS-correct line ending
}

fclose($file);

PHP_EOL se résout en \n sur Unix/macOS et \r\n sur Windows, ce qui rend les fichiers texte portables.

Toujours vérifier la valeur de retour

Les conditions de disque plein, les problèmes de permissions et les tuyaux cassés peuvent tous entraîner l'échec ou l'incomplétude des écritures. Traitez la valeur de retour comme source de vérité :

<?php

$file = fopen('report.txt', 'w');
if ($file === false) {
    throw new RuntimeException('Unable to open report.txt');
}

$data    = str_repeat('x', 1000);
$written = fwrite($file, $data);

if ($written === false || $written < strlen($data)) {
    fclose($file);
    throw new RuntimeException('Write failed or incomplete');
}

fclose($file);
echo "OK: $written bytes written";

fwrite() vs file_put_contents()

Pour une écriture unique en une seule fois, file_put_contents() est plus court — il ouvre, écrit et ferme en un seul appel :

<?php

// Equivalent of the basic example above, in one line:
file_put_contents('myfile.txt', 'Hello, world!');

Préférez fwrite() lorsque vous devez garder le fichier ouvert sur de nombreuses écritures (boucles, streaming, journalisation), passer des options comme le verrouillage, ou écrire de manière incrémentielle sans reconstruire toute la string en mémoire.

Pièges courants

• 'w' tronque immédiatement — au moment où fopen($f, 'w') réussit, l'ancien contenu est perdu, même si vous n'appelez jamais fwrite().
• Pas de sauts de ligne automatiques — vous devez ajouter \n / PHP_EOL vous-même.
• Oublier fclose() — les données peuvent rester dans un tampon et ne jamais atteindre le disque tant que le descripteur n'est pas fermé (ou que le script ne se termine pas).
• Les guillemets simples n'interprètent pas les séquences d'échappement — 'Line\n' écrit un backslash-n littéral. Utilisez "Line\n" pour un vrai saut de ligne.
• La limite length est en octets — avec du texte UTF-8 multi-octets, une limite en octets peut couper un caractère en deux.

Conclusion

fwrite() est la fonction principale de PHP pour écrire des strings dans un fichier ouvert. Maîtrisez le cycle en trois étapes ouvrir–écrire–fermer, choisissez le bon mode fopen() ('w' pour remplacer, 'a' pour ajouter), ajoutez vos propres sauts de ligne, vérifiez la valeur de retour, et vous pourrez écrire de tout, des simples fichiers texte aux journaux d'application durables.

Fonctions associées

• fopen() — ouvrir le fichier avant d'écrire
• fclose() — vider et fermer le descripteur après
• fread() et fgets() — relire les données
• file_put_contents() — écrire un fichier entier en un seul appel
• feof() — détecter la fin d'un fichier lors de la lecture

Pratique