fputs()

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

La fonction fputs() écrit une chaîne dans un fichier ouvert. C'est l'outil de base pour sauvegarder du texte sur disque en PHP : journaux, exports, fichiers de configuration générés, etc.

Le point le plus important à retenir sur fputs() est qu'elle est un alias de fwrite() — les deux fonctions sont identiques en tout point. PHP conserve fputs() parce que ce nom se lit comme "file put string" (placer une chaîne dans un fichier), ce qui est familier aux programmeurs venant du C. Le nouveau code préfère généralement fwrite(), mais les deux se comportent de manière identique, donc tout ce qui suit s'applique aux deux noms.

Syntaxe

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

• $stream — un pointeur de fichier (une ressource) retourné par fopen(). Il s'agit du fichier ouvert dans lequel vous écrivez, pas d'un nom de fichier.
• $data — la chaîne à écrire.
• $length — optionnel. Si fourni, l'écriture s'arrête après $length octets, même si $data est plus longue.

Elle retourne le nombre d'octets écrits, ou false en cas d'échec. Notez qu'elle retourne 0 et non false quand il n'y a rien à écrire, donc comparez toujours avec === pour vérifier les erreurs.

Comment utiliser la fonction fputs()

L'écriture dans un fichier suit toujours un schéma en trois étapes :

1. Ouvrir le fichier avec fopen() en choisissant un mode (voir ci-dessous).
2. Appeler fputs() autant de fois que nécessaire.
3. Fermer le fichier avec fclose() pour vider le tampon et libérer le handle.

<?php

$file = fopen('myfile.txt', 'w');   // open for writing, truncating the file
fputs($file, "Hello, world!\n");    // write a line
fclose($file);                      // flush + release the handle

Après exécution, myfile.txt contient Hello, world! suivi d'un saut de ligne. Le \n est entre guillemets doubles, donc PHP le convertit en vrai retour à la ligne (un \n littéral entre guillemets simples serait écrit tel quel).

Choisir le bon mode fopen()

Le mode passé à fopen() détermine l'endroit où fputs() écrit et si le contenu existant est préservé. Voici les modes qui permettent l'écriture :

Utilisez 'w' pour écraser, et 'a' (append) pour ajouter à un journal sans perdre ce qui s'y trouve déjà.

<?php

// Append three lines to a log; each run adds to the end.
$log = fopen('app.log', 'a');
fputs($log, "2026-06-21 user logged in\n");
fputs($log, "2026-06-21 report generated\n");
fclose($log);

Limiter la quantité écrite

Le troisième argument optionnel plafonne le nombre d'octets écrits. C'est utile quand vous ne voulez écrire qu'un préfixe d'une chaîne plus longue :

<?php

$file = fopen('clip.txt', 'w');
$written = fputs($file, 'Hello, world!', 5);  // write only the first 5 bytes
fclose($file);

echo $written;   // 5  — the file now contains "Hello"

$written vaut 5, et clip.txt ne contient que Hello.

Toujours vérifier la valeur de retour

Une écriture peut échouer — disque plein, fichier en lecture seule ou handle fermé. Comme fputs() peut légitimement retourner 0, testez le résultat avec la comparaison stricte === false :

<?php

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

if (fputs($file, 'data') === false) {
    echo 'Write failed!';
} else {
    echo 'Write succeeded.';
}

fclose($file);

Ceci affiche Write succeeded. et évite le bug classique où if (!fputs(...)) traite à tort une écriture de 0 octet valide comme une erreur.

fputs() vs. file_put_contents()

fputs() nécessite un handle ouvert et est idéale pour les écritures incrémentielles (de nombreuses petites écritures, comme une boucle de journal). Quand vous souhaitez simplement vider une chaîne entière dans un fichier en une seule fois, file_put_contents() effectue l'ouverture, l'écriture et la fermeture en un seul appel :

<?php

// Equivalent one-liner — no fopen()/fclose() needed.
file_put_contents('myfile.txt', "Hello, world!\n");

Préférez fputs()/fwrite() lorsque vous avez besoin de contrôler le handle (ajouts sur de nombreux appels, écritures partielles) ; préférez file_put_contents() pour les écritures uniques.

Résumé

• fputs() est un alias de fwrite() — même comportement, deux noms.
• Elle écrit dans un pointeur de fichier ouvert fourni par fopen(), donc associez-la toujours à fclose().
• Elle retourne le nombre d'octets, ou false en cas d'erreur — vérifiez avec === false.
• Choisissez 'w' pour écraser et 'a' pour ajouter ; un argument de longueur optionnel limite les octets écrits.
• Pour une écriture unique sur un fichier entier, préférez file_put_contents(). Pour relire les données, consultez fgets() et fread().

Pratique