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

ob_get_level() retourne le nombre de tampons de sortie actuellement actifs — c'est-à-dire la profondeur d'imbrication de la mise en tampon de sortie. Les tampons de sortie en PHP forment une pile : chaque appel à ob_start() empile un nouveau tampon, et chaque appel ob_end_* en dépile un. ob_get_level() vous indique la hauteur actuelle de cette pile.

C'est la méthode la plus sûre pour demander « la mise en tampon de sortie est-elle active ? » et « combien de couches y a-t-il ? » sans toucher au contenu mis en tampon. Cette page couvre la signature de la fonction, la valeur de retour, le fonctionnement de l'imbrication et les raisons courantes pour lesquelles vous pourriez l'utiliser.

Syntaxe

ob_get_level(): int

La fonction ne prend aucun argument et retourne un int :

• 0 — aucune mise en tampon de sortie n'est active.
• 1 — exactement un tampon est ouvert.
• 2, 3, … — autant de tampons sont imbriqués les uns sur les autres.

Elle ne lève jamais d'exception et ne produit jamais de sortie par elle-même, il est donc sûr de l'appeler n'importe où.

Un exemple de base

Lorsqu'aucun tampon n'a été démarré, le niveau est 0. Après un ob_start(), il devient 1 :

<?php

echo ob_get_level();   // 0 — nothing buffered yet

ob_start();
echo ob_get_level();   // 1 — one buffer is now active

ob_end_clean();
echo ob_get_level();   // 0 — buffer popped, back to baseline

Notez que les deux appels echo à l'intérieur du tampon sont eux-mêmes capturés par le tampon ; ob_end_clean() supprime ce texte capturé, donc la seule chose qui atteint le navigateur est le 0 final. Pour voir les valeurs intermédiaires pendant le développement, stockez-les d'abord dans des variables ou utilisez ob_get_clean() pour libérer le tampon.

Compter les tampons imbriqués

Comme les tampons s'empilent, appeler ob_start() deux fois vous donne un niveau de 2. C'est ce comportement qui rend ob_get_level() vraiment utile :

<?php

ob_start();                 // level 1
ob_start();                 // level 2

$level = ob_get_level();    // 2

ob_end_clean();             // level 1
ob_end_clean();             // level 0

echo "Deepest nesting was: {$level}";  // Deepest nesting was: 2

Les frameworks, les moteurs de templates et les gestionnaires d'arrêt ouvrent fréquemment leurs propres tampons, donc lors d'une vraie requête, le niveau peut déjà être 1 ou plus avant que votre propre code s'exécute.

Quand l'utiliser ?

• Nettoyage défensif. Avant d'envoyer des en-têtes ou de démarrer un nouveau tampon, videz ce qui est ouvert pour éviter qu'une sortie parasite ne casse votre réponse :

  <?php
  // Discard any buffers a framework or earlier code left open
  while (ob_get_level() > 0) {
      ob_end_clean();
  }

  Copier

• Vidage conditionnel. Ne videz que si un tampon est réellement actif, afin d'éviter un avertissement ob_end_flush() lorsqu'il n'en existe aucun :

  <?php
  if (ob_get_level() > 0) {
      ob_end_flush();
  }

  Copier

• Débogage des fuites de tampons. Enregistrer ob_get_level() au début et à la fin d'une requête vous aide à repérer un tampon qui a été ouvert mais jamais fermé.

Pièges courants

• ob_get_level() ne lit pas et ne vide pas le tampon — pour cela, utilisez ob_get_contents() ou ob_get_clean().
• Appeler ob_end_clean() / ob_end_flush() lorsque le niveau est 0 génère un avertissement. Protégez de tels appels avec une vérification ob_get_level() > 0, comme indiqué ci-dessus.
• Une configuration élevée de zlib.output_compression ou un framework peut faire en sorte que le niveau soit non nul dès la première ligne de votre script — ne supposez jamais qu'il commence à 0.

Conclusion

ob_get_level() rapporte la profondeur actuelle de la pile de tampons de sortie de PHP : 0 lorsque la mise en tampon est désactivée, et un nombre plus élevé pour chaque ob_start() imbriqué. Comme elle inspecte la pile sans consommer le contenu mis en tampon, c'est le bon outil pour protéger les opérations sur les tampons et pour vider proprement chaque tampon ouvert avant d'envoyer votre réponse finale.

Pratique