La fonction PHP ob_start() : tout ce que vous devez savoir

Lorsque PHP exécute un script, chaque echo, print ou bloc HTML est normalement envoyé immédiatement au client. La mise en tampon de sortie (output buffering) change cela : elle conserve tout ce que le script afficherait dans un tampon en mémoire, vous permettant de le capturer, le modifier ou le supprimer avant qu'il ne quitte jamais le serveur. La fonction ob_start() est la fonction intégrée qui active cette mise en tampon.

Ce chapitre explique ce que fait ob_start(), ses paramètres, comment capturer et transformer la sortie, les cas d'utilisation les plus courants et les pièges à éviter.

Qu'est-ce que la fonction ob_start() ?

ob_start() active la mise en tampon de sortie. Tant que la mise en tampon est active, rien de ce que le script affiche n'est envoyé au navigateur. Au lieu de cela, tout s'accumule dans un tampon interne jusqu'à ce que vous l'envoyiez explicitement (flush), le récupériez sous forme de chaîne ou le vidiez.

La seule chose que la mise en tampon ne retient pas sont les en-têtes HTTP. Comme le corps n'est plus envoyé immédiatement, vous pouvez toujours appeler des fonctions comme header() après avoir déjà affiché du contenu — c'est la raison la plus fréquente pour laquelle les développeurs utilisent ob_start().

Les tampons s'imbriquent également : chaque appel à ob_start() pousse un nouveau tampon sur une pile, et la fonction de fermeture/vidage correspondante dépile le plus récent. Vous pouvez vérifier la profondeur de la pile avec ob_get_level().

Syntaxe

ob_start(
    ?callable $callback = null,
    int $chunk_size = 0,
    int $flags = PHP_OUTPUT_HANDLER_STDFLAGS
): bool

Paramètres :

• $callback — Optionnel. Une fonction qui reçoit le contenu du tampon (et un masque de bits de statut) et retourne la chaîne à envoyer réellement. Utilisez-la pour transformer tout ce que le script affiche — par exemple, minifier le HTML ou le compresser en gzip.
• $chunk_size — Optionnel. Si supérieur à 0, le callback est invoqué chaque fois que le tampon atteint ce nombre d'octets, au lieu d'attendre uniquement que le tampon soit vidé. 0 (valeur par défaut) signifie vider uniquement à la fin.
• $flags — Optionnel. Un masque de bits contrôlant si le tampon peut être vidé, envoyé et supprimé. La valeur par défaut PHP_OUTPUT_HANDLER_STDFLAGS autorise les trois opérations.

Valeur de retour : true en cas de succès, false en cas d'échec.

Utilisation de base : capturer la sortie

Le modèle le plus courant consiste à démarrer un tampon, afficher quelque chose, puis le capturer dans une variable avec ob_get_clean() (qui retourne le tampon et désactive la mise en tampon en une seule étape) :

<?php

ob_start();                 // start buffering — nothing is sent yet
echo "Hello, ";
echo "world!";
$output = ob_get_clean();   // grab the buffer as a string, stop buffering

echo strtoupper($output);   // now we control what actually gets sent

Sortie :

HELLO, WORLD!

Ici, les deux appels echo n'atteignent jamais directement le client. ob_get_clean() retourne "Hello, world!", et seule la version en majuscules est finalement affichée. Ce flux "capturer, puis transformer" est ce qui rend la mise en tampon si puissante.

Transformer la sortie avec un callback

Au lieu de capturer manuellement, vous pouvez passer un callback à ob_start(). PHP l'exécute sur le tampon automatiquement lorsque celui-ci est vidé (ici, à la fin du script) :

<?php

function addBang(string $buffer): string
{
    return str_replace("world", "World!", $buffer);
}

ob_start("addBang");
echo "hello world";
// buffer is flushed automatically at script end → callback runs

Sortie :

hello World!

C'est exactement ainsi que fonctionnent les gestionnaires intégrés comme ob_gzhandler() — passez-le comme callback et toute votre page est compressée en gzip de manière transparente.

Cas d'utilisation courants

• Envoyer des en-têtes après la sortie. Comme le corps est mis en tampon, vous pouvez toujours appeler header() ou setcookie() après avoir affiché du HTML, évitant ainsi le redouté avertissement "headers already sent". Voir headers_sent().
• Templating. Capturer le HTML rendu d'un fichier de template dans une chaîne plutôt que de l'afficher directement, pour pouvoir le retourner, le mettre en cache ou l'intégrer dans une mise en page.
• Post-traitement de la page entière. Minifier le HTML, réécrire les URLs ou supprimer les commentaires via un callback avant que quoi que ce soit ne soit envoyé.
• Compression. Utiliser ob_gzhandler pour compresser les réponses sans modifier les appels echo de votre script.

Fonctions associées

Vous utiliserez rarement ob_start() seul. Ces fonctions gèrent le tampon qu'il crée :

• ob_get_contents() — Retourne le contenu du tampon sans le vider.
• ob_get_clean() — Retourne le tampon et désactive la mise en tampon.
• ob_clean() — Supprime le contenu du tampon mais maintient la mise en tampon active.
• ob_end_flush() — Envoie le tampon au client et désactive la mise en tampon.
• ob_end_clean() — Supprime le tampon et désactive la mise en tampon (n'envoie rien).
• ob_get_level() — Retourne le nombre de tampons imbriqués actuellement actifs.

Pour une vue d'ensemble plus large, voir PHP Output Control.

Pièges courants

• Fermez toujours ce que vous ouvrez. Chaque ob_start() doit être associé à un appel de vidage/nettoyage. Un tampon non fermé est vidé automatiquement à la fin du script, mais les laisser ouverts dans de longs scripts peut masquer la sortie ou gaspiller de la mémoire.
• ob_get_clean() retourne false si aucun tampon n'est actif. L'appeler sans un ob_start() correspondant donne false, pas une chaîne vide.
• La mise en tampon ≠ en-têtes illimités. Les en-têtes ne sont pas eux-mêmes mis en tampon ; seul le corps l'est. Une fois qu'un tampon est vidé vers le client, les en-têtes sont verrouillés.

Conclusion

ob_start() active la mise en tampon de sortie pour que PHP conserve la sortie du script en mémoire au lieu de l'envoyer immédiatement. Cela vous permet de capturer la sortie dans une chaîne, de la transformer avec un callback, d'envoyer des en-têtes après l'affichage ou de compresser une page entière. Associez-la à ob_get_clean() pour capturer, ob_end_flush() pour envoyer et ob_end_clean() pour supprimer — et n'oubliez jamais de fermer chaque tampon que vous ouvrez.

Practice