Fonctions de contrôle de sortie PHP : Tout ce que vous devez savoir

Normalement, chaque echo, print ou morceau de HTML dans un script PHP est envoyé au navigateur dès son exécution. La mise en tampon de sortie vous permet d'intercepter cette sortie et de la conserver en mémoire (un tampon) au lieu de l'envoyer immédiatement, afin de pouvoir l'inspecter, la modifier, la supprimer ou l'envoyer plus tard. Les fonctions de contrôle de sortie de PHP sont les outils intégrés qui gèrent ce tampon.

Ce chapitre explique ce qu'est la mise en tampon de sortie, pourquoi elle résout de vrais problèmes, et comment chaque fonction ob_* fonctionne — avec des exemples exécutables.

Pourquoi la mise en tampon de sortie est importante

La mise en tampon de sortie est plus qu'une curiosité. Elle résout plusieurs problèmes PHP courants :

• Éviter les erreurs "headers already sent". En PHP, vous devez appeler header() et setcookie() avant que toute sortie n'atteigne le navigateur. En mettant la sortie en tampon, vous pouvez encore envoyer des en-têtes après l'exécution de vos templates, car rien n'a encore été envoyé. Voir headers_sent().
• Capturer la sortie sous forme de chaîne. Rendu d'un template ou inclusion d'un fichier dont vous récupérez le résultat dans une variable plutôt que de l'afficher — la base de la plupart des moteurs de templates simples.
• Post-traiter toute la page. Minifiez le HTML, remplacez des espaces réservés ou compressez la sortie (gzip) en un seul endroit avant qu'elle ne soit envoyée.
• Ignorer une sortie indésirable. Éliminez le bruit provenant d'une bibliothèque tierce ou d'une instruction de débogage que vous ne voulez pas que l'utilisateur voie.

Les fonctions de contrôle de sortie

Voici les fonctions que vous utiliserez le plus souvent. Elles opèrent toutes sur le tampon démarré par ob_start().

Capturer la sortie sous forme de chaîne

L'utilisation la plus courante de la mise en tampon est de récupérer ce qu'un bloc de code affiche et de le stocker dans une variable. ob_get_clean() retourne le tampon et arrête la mise en tampon en un seul appel :

Rien n'atteint le navigateur jusqu'au echo final, qui affiche HELLO, WORLD!. Nous avons capturé le texte, l'avons transformé, puis seulement envoyé. C'est exactement ainsi que fonctionne une petite fonction de template :

<?php

function renderTemplate(string $name): string {
    ob_start();
    echo "Hello, $name!";
    return ob_get_clean();   // contents + stop buffering
}

echo renderTemplate("Ada");

Cela affiche Hello, Ada!. Dans un projet réel, le bloc mis en tampon serait un template HTML complet avec des balises <?= $name ?> intégrées.

Envoyer le tampon au navigateur

Quand vous souhaitez seulement retarder la sortie (sans la capturer), utilisez ob_end_flush() pour tout envoyer d'un coup :

Pendant que le tampon est ouvert, vous pouvez aussi l'inspecter avec ob_get_length() et ob_get_level() :

<?php

ob_start();
echo "buffered text";
echo "\nLevel: " . ob_get_level();   // 1 — one buffer is active
echo "\nLength: " . ob_get_length(); // bytes captured so far
ob_end_flush();

ob_get_level() retourne 1 car un seul tampon est actif ; si vous appelez ob_start() à nouveau à l'intérieur, le niveau devient 2 (les tampons s'empilent comme une pile).

Transformer la sortie avec un callback

ob_start() accepte un callback qui reçoit l'intégralité du tampon et retourne la version modifiée. C'est ainsi que fonctionnent les minificateurs de sortie et les filtres de recherche-remplacement :

<?php

ob_start(function (string $buffer): string {
    return str_replace("cat", "dog", $buffer);
});

echo "I have a cat.";
ob_end_flush();

Le callback s'exécute lors de l'envoi du tampon, donc la page affiche I have a dog.. Le même modèle alimente ob_gzhandler, le callback intégré de PHP pour compresser la sortie en gzip.

Pièges courants

• Fermez toujours ce que vous ouvrez. Chaque ob_start() doit être suivi d'un appel flush ou clean. Un tampon non équilibré laisse la sortie bloquée en mémoire et elle n'atteint jamais l'utilisateur.
• Les tampons s'imbriquent. Chaque ob_start() ajoute un niveau. ob_get_clean() ferme uniquement le plus interne ; utilisez ob_get_level() dans une boucle si vous devez en dépiler plusieurs.
• ob_get_contents() n'arrête pas la mise en tampon — seules les fonctions *_clean et *_end_* le font. Les confondre est une source fréquente de sortie dupliquée.
• Un tampon a une taille finie. Par défaut, PHP vide automatiquement le tampon lorsqu'il atteint output_buffering octets (php.ini), donc ne comptez pas dessus pour conserver une quantité illimitée de données.

Conclusion

La mise en tampon de sortie vous donne le contrôle sur quand et comment la sortie de votre script est envoyée. Utilisez-la pour capturer du contenu rendu sous forme de chaîne, pour envoyer des en-têtes après la génération d'une page, pour ignorer une sortie indésirable, ou pour post-traiter toute la réponse en un seul endroit. Une fois que vous comprenez le cycle démarrage/récupération/nettoyage/envoi, la famille ob_* est petite et prévisible.

Lectures complémentaires : echo and print, PHP header(), PHP Sessions, et PHP Cookies.

Pratique