Fonction PHP ob_end_flush() : tout ce que vous devez savoir

Lorsque PHP capture la sortie dans un tampon au lieu de l'envoyer directement au navigateur, vous devez éventuellement libérer ce tampon. La fonction ob_end_flush() fait exactement cela : elle envoie le contenu du tampon de sortie le plus interne au niveau suivant (le navigateur, ou un tampon externe) puis supprime ce tampon. Cette page explique ce que fait la fonction, quand l'utiliser, en quoi elle diffère de ses proches cousines, et les pièges à éviter.

Ce que fait la fonction ob_end_flush()

ob_end_flush() effectue deux opérations sur le tampon de sortie actif le plus interne (en haut de la pile) :

1. Elle vide le tampon — son contenu est transmis au tampon parent, ou envoyé au client si c'était le dernier tampon de la pile.
2. Elle désactive ce tampon, en le retirant de la pile de tampons.

Elle retourne true en cas de succès, ou false si aucun tampon actif n'existe (par exemple, vous l'appelez deux fois, ou vous n'avez jamais appelé ob_start()). En cas d'échec, elle émet également un E_NOTICE.

Les tampons forment une pile. Chaque ob_start() empile un nouveau tampon au sommet. ob_end_flush() n'agit que sur celui qui se trouve actuellement au sommet, pas sur tous les tampons à la fois. Vérifiez combien sont ouverts avec ob_get_level().

Syntaxe

ob_end_flush(): bool

La fonction ne prend aucun argument et retourne un booléen.

Exemple de base

<?php

ob_start();                       // start capturing output
echo "This will be buffered";     // goes into the buffer, not the screen yet
$ok = ob_end_flush();             // send the buffer out, then close it

var_dump($ok);                    // bool(true)

Sortie :

This will be bufferedbool(true)

ob_start() ouvre le tampon, le echo y est stocké, et ob_end_flush() libère le texte vers le navigateur et met fin à la mise en tampon. Le var_dump() s'exécute une fois le tampon supprimé, donc sa sortie est envoyée directement.

Quand utiliser cette fonction ?

La mise en tampon de sortie est particulièrement utile lorsque vous devez décider tardivement ce que vous voulez faire avec une sortie déjà générée :

• Capturer, puis inspecter ou modifier — mettez en tampon une section, lisez-la avec ob_get_contents(), modifiez-la si nécessaire, puis utilisez ob_end_flush() pour envoyer le résultat (éventuellement modifié).
• Envoyer des en-têtes après la sortie — comme rien n'atteint le client tant que la mise en tampon est active, vous pouvez encore appeler header() ou setcookie() même après avoir utilisé echo pour du balisage. ob_end_flush() libère tout une fois les en-têtes définis.
• Gabarits imbriqués — enveloppez un tampon interne, videz-le dans un tampon externe qui effectue un traitement supplémentaire.

Si vous souhaitez plutôt conserver le texte capturé dans une variable plutôt que de l'envoyer, utilisez ob_get_clean(). Si vous voulez jeter la sortie, utilisez ob_end_clean().

ob_end_flush() par rapport aux fonctions associées

Un moyen facile de s'en souvenir : flush envoie, clean supprime, get_ vous donne aussi la chaîne, et end_ ferme le tampon au lieu de le laisser ouvert.

Vider des tampons imbriqués

Comme ob_end_flush() ne ferme qu'un seul niveau, vous devez l'appeler une fois par tampon pour dérouler complètement la pile :

<?php

ob_start();                 // level 1
echo "outer ";

ob_start();                 // level 2
echo "inner";

echo ob_get_level();        // 2 — captured into level 2

ob_end_flush();             // level 2 flushes into level 1
ob_end_flush();             // level 1 flushes to the browser

Sortie :

outer inner2

Le echo interne et le compteur de niveau atterrissent tous deux dans le tampon 2 ; le premier ob_end_flush() les fusionne dans le tampon 1, et le second envoie le tout au client.

Pièges courants

• L'appeler sans tampon actif retourne false et génère une notice. Protégez-vous avec if (ob_get_level() > 0) si vous n'êtes pas sûr qu'un tampon soit ouvert.
• Elle ne vide pas tout — un appel ferme un tampon. Bouclez jusqu'à ce que ob_get_level() soit à 0 pour dérouler chaque niveau.
• Ne la confondez pas avec flush(). La fonction flush() seule pousse les tampons d'écriture PHP/SAPI vers le client mais ne touche pas à la pile de mise en tampon de sortie.

Conclusion

ob_end_flush() envoie le tampon de sortie courant au niveau suivant, puis ferme ce tampon. Utilisez-la lorsque vous avez utilisé ob_start() pour capturer une sortie et souhaitez maintenant la libérer. N'oubliez pas que les tampons forment une pile, que la fonction n'agit que sur le plus haut, et que ses cousines clean/get_ offrent les variantes d'abandon et de retour dont vous pourriez avoir besoin à la place.

Pratique