Fonction PHP flush() : Envoyer la sortie au navigateur immédiatement

Par défaut, PHP collecte le texte que votre script affiche (avec echo, print, etc.) et l'envoie au navigateur par blocs — souvent seulement à la fin du script. La fonction intégrée flush() vous permet de pousser tout ce qui a déjà été produit immédiatement, afin que l'utilisateur voie une sortie partielle avant que la page soit entièrement générée. Cette page explique ce que fait flush(), en quoi elle diffère de ob_flush(), les tampons qui se trouvent entre votre script et le navigateur, et dans quels cas l'utiliser est réellement utile.

Ce que fait la fonction flush()

flush(): void

flush() demande à PHP de transmettre toute sortie qu'il retient à la couche inférieure — le SAPI et le serveur web. Elle ne prend aucun argument et ne retourne rien. Un cas d'usage courant est un script de longue durée qui devrait afficher sa progression (une ligne de journal, un compteur) au lieu de laisser l'utilisateur fixer une page blanche jusqu'à la fin.

Deux limites importantes :

• flush() n'affecte pas la couche de mise en mémoire tampon de sortie propre à PHP (celle démarrée avec ob_start()). Si la mise en mémoire tampon est active, le texte est toujours bloqué dans le tampon de PHP et flush() n'a rien à envoyer. Vous devez d'abord libérer cette couche avec ob_flush() ou ob_end_flush().
• flush() ne peut pas contourner la mise en mémoire tampon effectuée par le serveur web ou le proxy (Apache mod_deflate, Nginx proxy_buffering, FastCGI, gzip). Ces couches peuvent toujours retenir les données jusqu'à ce qu'elles décident de les envoyer.

Un exemple de base

Lorsqu'aucune mise en mémoire tampon de sortie PHP n'est activée, flush() seul suffit à pousser la sortie actuelle :

<?php
echo "Starting a slow task...\n";
flush();        // send the line above to the browser now

sleep(2);       // pretend we are doing real work

echo "Done!\n";
?>

Sans l'appel à flush(), l'utilisateur verrait typiquement les deux lignes apparaître ensemble après 2 secondes. Avec lui, « Starting a slow task... » peut arriver immédiatement.

flush() vs ob_flush()

C'est la distinction qui déroute les gens. PHP peut empiler deux tampons séparés, et chaque fonction *flush cible un tampon différent :

Lorsque la mise en mémoire tampon de sortie est activée, vous avez besoin des deux, dans l'ordre — ob_flush() d'abord pour libérer le tampon de PHP, puis flush() pour le pousser plus loin :

<?php
ob_start();             // turn on PHP output buffering
echo "Buffered text\n";

ob_flush();             // PHP buffer -> SAPI buffer
flush();                // SAPI buffer -> browser
?>

Inversez l'ordre ou omettez ob_flush() et le texte reste bloqué dans PHP. Si vous souhaitez que PHP vide automatiquement après chaque echo, consultez ob_implicit_flush().

Pourquoi ça « ne fonctionne souvent pas »

La diffusion de la sortie de manière fiable est plus difficile qu'appeler une seule fonction, car plusieurs couches mettent en mémoire tampon indépendamment :

• gzip / compression — zlib.output_compression et mod_deflate d'Apache doivent accumuler suffisamment d'octets avant d'envoyer. Désactivez la compression pour la réponse que vous souhaitez diffuser.
• Mise en mémoire tampon du serveur web / proxy — Nginx (proxy_buffering on), FastCGI et les équilibreurs de charge remettent couramment en mémoire tampon la réponse.
• Rendu du navigateur — certains navigateurs attendent un nombre minimum d'octets avant de peindre ; compléter la sortie peut forcer un affichage anticipé.

Pour ces raisons, flush() est mieux traitée comme un indice, pas comme une garantie. Pour les besoins de diffusion modernes (événements envoyés par le serveur, API en morceaux), configurez le serveur explicitement plutôt que de vous fier uniquement à flush().

Fonctions de sortie associées

• ob_flush() — vide le tampon de contrôle de sortie de PHP.
• ob_end_flush() — vide et désactive la mise en mémoire tampon de sortie.
• ob_get_flush() — retourne le contenu du tampon et le vide.
• PHP Output Control — vue d'ensemble de la façon dont les couches de mise en mémoire tampon s'articulent.
• fflush() — vide les écritures en mémoire tampon vers un fichier ouvert (pas le navigateur).

Conclusion

flush() force PHP à envoyer la sortie qu'il a déjà produite vers le navigateur au lieu d'attendre la fin du script. N'oubliez pas qu'elle ne touche que le tampon SAPI/écriture : avec ob_start() actif, vous devez d'abord appeler ob_flush(), et même dans ce cas le serveur web ou la couche de compression peut retarder la livraison. Utilisée avec cette compréhension, flush() est un moyen pratique de diffuser la progression de scripts de longue durée.

Pratique