fflush()

Introduction à la fonction PHP fflush()

La fonction fflush() en PHP force l'écriture immédiate de toutes les données encore présentes dans le tampon d'écriture d'un pointeur de fichier vers le flux sous-jacent immédiatement, au lieu d'attendre que le tampon soit plein ou que le flux soit fermé.

Lorsque vous appelez fwrite(), PHP ne pousse pas nécessairement les octets directement sur le disque. Pour des raisons de performance, les données sont collectées dans un tampon en mémoire et écrites en blocs plus importants. C'est généralement ce que vous souhaitez — mais parfois vous avez besoin que les données soient écrites maintenant : un fichier de log consultable en temps réel, un processus de travail de longue durée lu par un autre processus, ou un script susceptible d'être interrompu avant de se terminer. fflush() est la fonction qui dit « n'attends pas, écris ce que tu as. »

Cette page couvre la syntaxe, les paramètres, la valeur de retour et plusieurs exemples exécutables, ainsi que les pièges courants — y compris la différence cruciale entre fflush() et la synchronisation au niveau du système d'exploitation.

Syntaxe

La syntaxe de la fonction fflush() est la suivante :

La syntaxe PHP de fflush()

bool fflush ( resource $stream )

• stream : le pointeur de fichier à vider

Paramètres

La fonction fflush() prend un paramètre obligatoire :

• $stream : Le pointeur de fichier à vider. Il doit s'agir d'une ressource de flux valide et accessible en écriture — généralement celle renvoyée par fopen(). Les flux ouverts en lecture seule (mode 'r') n'ont rien à vider.

Valeur de retour

fflush() renvoie true en cas de succès ou false en cas d'échec. Elle échoue lorsque la ressource n'est pas un flux ouvert valide ou lorsque l'écriture sous-jacente ne peut pas être effectuée ; un avertissement peut être émis. Étant donné que les échecs sont rares mais réels (disque plein, pipe cassé), vérifiez la valeur de retour lorsque l'écriture ne doit pas être perdue :

<?php

if (fflush($stream) === false) {
    // The buffered data could not be written — handle it (log, retry, abort).
}

Exemples

Exemple 1 : Vider un pointeur de fichier

Ouvrez un fichier, écrivez des données, puis videz le tampon pour que les octets atteignent le flux avant que le script ne continue :

Vider un pointeur de fichier en PHP

<?php

$fileHandle = fopen('example.txt', 'w');
fwrite($fileHandle, 'Hello, World!');

if (fflush($fileHandle)) {
    echo "Buffer flushed to the stream.\n";
}

fclose($fileHandle);

Sortie :

Buffer flushed to the stream.

Exemple 2 : Un log vidé en continu

Un processus de travail qui ajoute des entrées à un fichier de log et vide le tampon après chaque entrée, afin qu'un autre processus puisse faire tail -f sur le fichier et voir les lignes apparaître en temps réel plutôt que par rafales :

Journalisation en temps réel avec fflush()

<?php

$log = fopen('worker.log', 'a');

foreach (['started', 'processing', 'done'] as $event) {
    fwrite($log, date('c') . " {$event}\n");
    fflush($log); // each line is visible immediately, not only at fclose()
}

fclose($log);

Sans l'appel à fflush(), les trois lignes n'apparaîtraient normalement que lorsque le tampon serait plein ou lorsque fclose() s'exécuterait à la fin.

fflush() vs. fclose()

Vous n'avez pas besoin de fflush() juste avant fclose() — fclose() vide automatiquement toutes les données restantes dans le tampon avant de fermer la ressource. Utilisez fflush() uniquement lorsque vous avez besoin que les données soient écrites pendant que le fichier est encore ouvert.

fflush() ne garantit pas que les données sont sur le disque

C'est l'idée reçue la plus courante. fflush() pousse le tampon de PHP vers le système d'exploitation, mais l'OS conserve son propre cache d'écriture. Après fflush(), les octets peuvent toujours se trouver dans le cache de l'OS plutôt que sur le disque physique. Si la machine perd de l'alimentation immédiatement après, les données peuvent être perdues.

Pour forcer l'OS à écrire les données sur un stockage durable, utilisez ensuite fsync() (PHP 8.1+) :

<?php

$file = fopen('important.txt', 'w');
fwrite($file, 'critical data');
fflush($file); // PHP buffer -> OS
fsync($file);  // OS cache -> physical disk (PHP 8.1+)
fclose($file);

Contrôle du tampon lui-même

Si vous souhaitez modifier la quantité que PHP met en tampon avant d'écrire automatiquement — plutôt que de vider le tampon à la demande — utilisez set_file_buffer(). Définir la taille du tampon à 0 désactive entièrement la mise en tampon, de sorte que chaque fwrite() est écrit directement sans nécessiter un fflush() explicite.

Remarque sur la mise en tampon de sortie

Ne confondez pas fflush() avec les fonctions de mise en tampon de sortie de PHP comme ob_flush() et flush(). fflush() opère sur une ressource de fichier/flux (fichiers, sockets, pipes). ob_flush() vide le tampon de sortie interne de PHP (le corps de la page) vers le serveur web ou le client. Ce sont des mécanismes distincts qui partagent simplement le mot « flush ».

Conclusion

En conclusion, la fonction fflush() est une fonction PHP utile qui garantit que les données en tampon sont immédiatement écrites dans un flux de fichier. Elle est essentielle pour les applications nécessitant une persistance des données en temps réel, telles que les systèmes de journalisation ou les scripts de traitement de données.

En utilisant les exemples fournis dans cet article, vous devriez maintenant être en mesure d'utiliser la fonction fflush() dans votre code PHP facilement. Si vous avez des questions ou des préoccupations concernant l'utilisation de la fonction fflush() en PHP, n'hésitez pas à nous contacter. Nous serons heureux de vous aider.

Pratique