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

La fonction ob_list_handlers() renvoie un tableau contenant les noms de chaque gestionnaire de tampon de sortie actuellement actif, classés du tampon le plus externe au plus interne. La mise en tampon de sortie permet à PHP de collecter la sortie générée en mémoire plutôt que de l'envoyer directement au navigateur ; un gestionnaire est le callback optionnel que vous associez à un tampon avec ob_start() pour transformer cette sortie avant qu'elle ne soit vidée. Cette page couvre la syntaxe, la valeur de retour, la façon dont PHP nomme chaque gestionnaire et les cas où l'utilisation de ob_list_handlers() s'avère réellement utile.

Syntaxe

ob_list_handlers(): array

La fonction ne prend aucun argument et renvoie un tableau de chaînes. Lorsqu'aucun tampon de sortie n'est actif, elle renvoie un tableau vide.

À quoi ressemblent les noms des gestionnaires

Les chaînes renvoyées ne sont pas le contenu du tampon — ce sont des étiquettes qui identifient chaque gestionnaire. L'étiquette dépend de la façon dont le tampon a été ouvert :

Étant donné que toutes les fonctions anonymes sont rapportées comme "Closure::__invoke", il est impossible de distinguer deux closures différentes à partir de ce tableau — nommez vos fonctions de gestionnaire si vous avez besoin de les identifier ultérieurement.

Utilisation de base

Appelez ob_list_handlers() et parcourez le résultat. Lorsque rien n'est mis en tampon, le tableau est vide, alors gérez ce cas :

<?php

$handlers = ob_list_handlers();

if (empty($handlers)) {
    echo "No output handlers are active.\n";
} else {
    foreach ($handlers as $handler) {
        echo $handler . "\n";
    }
}

Sans tampon démarré, cela affiche :

No output handlers are active.

Inspection des gestionnaires imbriqués

Les tampons de sortie s'empilent : chaque ob_start() ouvre un nouveau tampon au-dessus du précédent. ob_list_handlers() reflète toute cette pile, ce qui est pratique pour voir exactement ce qui est superposé.

<?php

function uppercase_handler(string $buffer): string
{
    return strtoupper($buffer);
}

ob_start();                       // default buffer, no callback
ob_start('uppercase_handler');    // named callback
ob_start(function ($buffer) {     // anonymous callback
    return trim($buffer);
});

print_r(ob_list_handlers());

Sortie :

Array
(
    [0] => default output handler
    [1] => uppercase_handler
    [2] => Closure::__invoke
)

L'ordre correspond à l'ordre dans lequel les tampons ont été ouverts : l'index 0 est le tampon le plus externe (premier), et le dernier index est le plus interne (démarré en dernier).

Quand utiliser cette fonction ?

ob_list_handlers() est un outil de diagnostic, pas quelque chose que vous appelez lors d'un traitement de requête normal. Faites-y appel lorsque vous avez besoin de :

• Déboguer des erreurs "headers already sent" ou une sortie inattendue en confirmant quelles couches de mise en tampon sont actives.
• Éviter la double compression — recherchez "ob_gzhandler" avant d'ajouter votre propre gestionnaire gzip, car le paramètre INI zlib.output_compression peut en avoir déjà enregistré un.
• Vérifier le comportement d'un framework ou d'un middleware, car de nombreux frameworks ouvrent leurs propres tampons et vous ne savez peut-être pas quelle est la profondeur de la pile.

Pour compter les tampons actifs plutôt que de les nommer, ob_get_level() renvoie directement la profondeur :

<?php

ob_start();
ob_start('ob_gzhandler');

echo count(ob_list_handlers()), "\n"; // 2
echo ob_get_level(), "\n";            // 2

Sortie :

2
2

Pièges courants

• Un tableau vide est normal. Un retour de [] signifie simplement qu'aucun tampon n'est ouvert — ce n'est pas une erreur.
• Un nom par tampon. Un tampon démarré sans callback apparaît quand même, sous le nom "default output handler" ; le nom reflète le gestionnaire, pas l'existence du tampon.
• Les noms ne sont pas appelables. Les chaînes sont de simples étiquettes. Vous ne pouvez pas passer "Closure::__invoke" à ob_start() pour recréer le même gestionnaire.

Fonctions associées

• ob_start() — ouvre un nouveau tampon de sortie et attache optionnellement un gestionnaire.
• ob_get_level() — obtient le niveau d'imbrication de la mise en tampon de sortie.
• ob_get_contents() — lit le contenu du tampon courant.
• ob_end_flush() / ob_end_clean() — ferme le tampon le plus en haut.
• PHP Output Control — vue d'ensemble de la famille de mise en tampon de sortie.

Conclusion

ob_list_handlers() vous donne un aperçu rapide en lecture seule de la pile de tampons de sortie, en nommant chaque gestionnaire actif du plus externe au plus interne. Elle est particulièrement utile pour déboguer des problèmes de mise en tampon ou avant d'enregistrer un gestionnaire (comme gzip) qui pourrait déjà être présent. Associez-la à ob_get_level() lorsque vous n'avez besoin que du comptage.

Pratique