Fonction PHP ob_flush() : Tout ce que vous devez savoir

Par défaut, PHP conserve votre sortie dans un tampon et l'envoie au client en une seule fois. Parfois, vous souhaitez transmettre ce que vous avez jusqu'à présent au navigateur sans terminer le tampon — par exemple, pour diffuser un long rapport ligne par ligne ou afficher la progression d'une tâche lente. La fonction ob_flush() fait exactement cela : elle envoie le contenu du tampon de sortie actif vers le niveau suivant, puis le vide, tout en maintenant la mise en tampon active pour que vous puissiez continuer à collecter des données. Ce chapitre explique comment ob_flush() s'intègre dans la chaîne de mise en tampon de sortie de PHP, quand y recourir, et les pièges courants.

Ce que fait ob_flush()

ob_flush() envoie le contenu du tampon de sortie le plus haut au niveau suivant — le tampon suivant dans la pile, ou la couche d'écriture interne de PHP s'il s'agit du seul tampon. Après le vidage, ce tampon est effacé mais reste ouvert, de sorte que les echo suivants sont de nouveau capturés.

Signature:  ob_flush(): void
Returns:    nothing (void); emits a warning if no buffer is active
PHP:        4.0+ (return type became void in PHP 8.0)

Deux notions sont faciles à confondre :

• ob_flush() déplace les données hors du tampon PHP mais ne garantit pas qu'elles atteignent le navigateur. Il peut y avoir un autre tampon au-dessus, plus le tampon d'écriture propre à PHP et le tampon du serveur web.
• flush() pousse les tampons d'écriture de PHP vers le client. Pour que les octets transitent réellement sur le réseau, vous appelez généralement les deux, dans l'ordre : ob_flush() puis flush().

Elle doit être couplée à ob_start(). Appeler ob_flush() sans tampon actif génère un notice/warning et ne fait rien.

Syntaxe

ob_flush();

Elle ne prend aucun argument et ne renvoie aucune valeur.

Exemple de base

Activez la mise en tampon, écrivez quelque chose, puis videz le tampon :

<?php

ob_start();              // 1. Enable output buffering
echo "This will be buffered";
ob_flush();              // 2. Flush PHP buffer to the next level
flush();                 // 3. Push it toward the client

Sortie :

This will be buffered

ob_start() ouvre un tampon, le echo y est capturé, ob_flush() libère ce texte, et flush() le pousse vers le navigateur. Fait important : le tampon reste ouvert après cela — vous pourriez echo et vider à nouveau.

Diffusion progressive de la sortie

L'utilisation réelle la plus courante de ob_flush() consiste à envoyer la sortie par morceaux afin que l'utilisateur voie les résultats au fur et à mesure qu'ils sont produits, plutôt que d'attendre la fin du script entier :

<?php

ob_start();

for ($i = 1; $i <= 5; $i++) {
    echo "Processing item $i\n";
    ob_flush();          // hand this line to the next level
    flush();             // and on toward the browser
    // sleep(1);         // (a real task would do work here)
}

Sortie :

Processing item 1
Processing item 2
Processing item 3
Processing item 4
Processing item 5

Sur un serveur en production avec le sleep(1) décommenté, chaque ligne apparaîtrait à une seconde d'intervalle plutôt que toutes à la fin.

ob_flush() vs. ob_end_flush() vs. ob_get_clean()

Choisir la mauvaise fonction de vidage est la source habituelle de bugs. Elles diffèrent de deux façons : si le tampon reste ouvert, et où va le contenu.

Utilisez ob_flush() lorsque vous souhaitez émettre de la progression tout en continuant la mise en tampon. Utilisez ob_end_flush() lorsque vous avez entièrement terminé. Utilisez ob_get_clean() lorsque vous souhaitez capturer le tampon dans une variable plutôt que de l'envoyer.

Pièges courants

• La mise en tampon côté serveur peut toujours retenir la sortie. Apache, Nginx (mise en tampon FastCGI), la compression gzip et les proxys peuvent conserver vos octets vidés jusqu'à en avoir « assez ». ob_flush() + flush() ne contrôlent que le côté PHP.
• zlib.output_compression casse le streaming. Lorsque la compression gzip est activée, les vidages intermédiaires sont généralement mis en tampon pour la compression, de sorte que les morceaux ne s'écouleront pas progressivement. Désactivez-la pour les points d'accès de streaming.
• Pas de tampon = avertissement. Appeler ob_flush() sans ob_start() correspondant déclenche un avertissement. Vérifiez le niveau actif avec ob_get_level() si vous n'êtes pas sûr.
• Cela vide le tampon. Après ob_flush(), le tampon est effacé, vous ne pouvez donc pas lire son contenu précédent par la suite.
• Forcer le vidage immédiat globalement. ob_implicit_flush(true) fait en sorte que chaque instruction de sortie se vide automatiquement, supprimant ainsi le besoin d'appeler ob_flush() après chaque echo.

Conclusion

ob_flush() envoie le tampon de sortie actuel vers le niveau suivant tout en maintenant la mise en tampon active, ce qui en fait le bon outil pour diffuser la progression ou de grandes réponses de manière incrémentielle. N'oubliez pas la chaîne : ob_start() ouvre le tampon, ob_flush() libère son contenu au niveau suivant, et flush() les pousse vers le client — et que la mise en tampon côté serveur ou la compression gzip peut toujours retarder la livraison indépendamment de ce que fait votre code PHP.

Pratique