Função PHP ob_get_level(): Tudo o Que Você Precisa Saber

ob_get_level() retorna quantos buffers de saída estão ativos no momento — ou seja, quão profundamente o buffer de saída está aninhado. Os buffers de saída no PHP formam uma pilha: cada chamada a ob_start() empurra um novo buffer para a pilha, e cada chamada ob_end_* remove um. ob_get_level() informa a altura atual dessa pilha.

Esta é a forma mais segura de perguntar "o buffer de saída está ativo?" e "quantas camadas existem?" sem tocar no conteúdo armazenado em buffer. Esta página aborda a assinatura da função, o valor de retorno, como o aninhamento funciona e os motivos comuns pelos quais você a utilizaria.

Sintaxe

ob_get_level(): int

A função não recebe argumentos e retorna um int:

• 0 — nenhum buffer de saída está ativo.
• 1 — exatamente um buffer está aberto.
• 2, 3, … — essa quantidade de buffers está aninhada uns sobre os outros.

Ela nunca lança exceções e nunca produz saída própria, portanto é seguro chamá-la em qualquer lugar.

Um exemplo básico

Quando nenhum buffer foi iniciado, o nível é 0. Após um ob_start() ele se torna 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

Observe que as duas chamadas echo dentro do buffer são capturadas por ele; ob_end_clean() descarta esse texto capturado, portanto a única coisa que chega ao navegador é o 0 final. Para ver os valores intermediários durante o desenvolvimento, armazene-os em variáveis primeiro ou use ob_get_clean() para liberar o buffer.

Contando buffers aninhados

Como os buffers formam uma pilha, chamar ob_start() duas vezes resulta em um nível 2. Este é o comportamento que torna ob_get_level() genuinamente útil:

<?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

Frameworks, mecanismos de templates e manipuladores de desligamento frequentemente abrem seus próprios buffers, portanto em uma requisição real o nível já pode ser 1 ou mais antes que seu próprio código seja executado.

Quando eu usaria isso?

• Limpeza defensiva. Antes de enviar cabeçalhos ou iniciar um novo buffer, esvazie o que estiver aberto para que saídas indevidas não quebrem sua resposta:

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

  Copiar

• Flush condicional. Somente faça flush se um buffer estiver realmente ativo, evitando um aviso de ob_end_flush() quando nenhum existir:

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

  Copiar

• Depuração de vazamentos de buffer. Registrar ob_get_level() no início e no fim de uma requisição ajuda a identificar um buffer que foi aberto mas nunca fechado.

Armadilhas

• ob_get_level() não lê nem limpa o buffer — para isso use ob_get_contents() ou ob_get_clean().
• Chamar ob_end_clean() / ob_end_flush() quando o nível é 0 gera um aviso. Proteja essas chamadas com uma verificação ob_get_level() > 0, conforme mostrado acima.
• Uma configuração alta de zlib.output_compression ou de framework pode fazer com que o nível seja diferente de zero desde a primeira linha do seu script — nunca assuma que começa em 0.

Conclusão

ob_get_level() reporta a profundidade atual da pilha de buffer de saída do PHP: 0 quando o buffer está desligado, e um número maior para cada ob_start() aninhado. Como inspeciona a pilha sem consumir o conteúdo armazenado em buffer, é a ferramenta certa para proteger operações de buffer e para esvaziar completamente todos os buffers abertos antes de enviar sua resposta final.

Prática