Função PHP ob_list_handlers(): Tudo o que Você Precisa Saber

A função ob_list_handlers() retorna um array contendo os nomes de todos os handlers de buffer de saída atualmente ativos, ordenados do buffer mais externo ao mais interno. O buffer de saída permite que o PHP colete a saída gerada em memória em vez de enviá-la diretamente ao navegador; um handler é o callback opcional que você anexa a um buffer com ob_start() para transformar essa saída antes de ela ser enviada. Esta página aborda a sintaxe, o valor de retorno, como o PHP nomeia cada handler e quando usar ob_list_handlers() é realmente útil.

Sintaxe

ob_list_handlers(): array

A função não recebe argumentos e retorna um array de strings. Quando nenhum buffer de saída está ativo, ela retorna um array vazio.

Como São os Nomes dos Handlers

As strings retornadas não são o conteúdo do buffer — são rótulos que identificam cada handler. O rótulo depende de como o buffer foi aberto:

Como funções anônimas são todas reportadas como "Closure::__invoke", não é possível distinguir duas closures diferentes por meio deste array — nomeie suas funções de handler se precisar identificá-las posteriormente.

Uso Básico

Chame ob_list_handlers() e itere sobre o resultado. Quando nada está em buffer, o array está vazio, então verifique esse caso:

<?php

$handlers = ob_list_handlers();

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

Sem nenhum buffer iniciado, isso imprime:

No output handlers are active.

Inspecionando Handlers Aninhados

Os buffers de saída se empilham: cada ob_start() abre um novo buffer sobre o anterior. ob_list_handlers() reflete toda essa pilha, por isso é útil para ver exatamente o que está em camadas.

<?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());

Saída:

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

A ordem corresponde à ordem em que os buffers foram abertos: o índice 0 é o buffer mais externo (primeiro), e o último índice é o mais interno (iniciado mais recentemente).

Quando Usar Isso?

ob_list_handlers() é uma ferramenta de diagnóstico, não algo que você chama no tratamento normal de requisições. Recorra a ela quando precisar:

• Depurar erros de "headers already sent" ou saída inesperada confirmando quais camadas de buffer estão em uso.
• Evitar compressão dupla — verifique a presença de "ob_gzhandler" antes de adicionar seu próprio handler gzip, pois a configuração INI zlib.output_compression pode já ter registrado um.
• Verificar o comportamento de frameworks ou middlewares, já que muitos frameworks abrem seus próprios buffers e você pode não saber a profundidade da pilha.

Para contar os buffers ativos em vez de nomeá-los, ob_get_level() retorna a profundidade diretamente:

<?php

ob_start();
ob_start('ob_gzhandler');

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

Saída:

2
2

Armadilhas Comuns

• Array vazio é normal. Um retorno de [] simplesmente significa que nenhum buffer está aberto — não é um erro.
• Um nome por buffer. Um buffer iniciado sem callback ainda aparece como "default output handler"; o nome reflete o handler, não a existência do buffer.
• Os nomes não são chamáveis. As strings são apenas rótulos. Você não pode passar "Closure::__invoke" de volta para ob_start() para recriar o mesmo handler.

Funções Relacionadas

• ob_start() — abre um novo buffer de saída e opcionalmente anexa um handler.
• ob_get_level() — obtém o nível de aninhamento do buffer de saída.
• ob_get_contents() — lê o conteúdo do buffer atual.
• ob_end_flush() / ob_end_clean() — fecha o buffer mais recente.
• PHP Output Control — visão geral da família de buffer de saída.

Conclusão

ob_list_handlers() fornece um snapshot rápido e somente de leitura da pilha de buffers de saída, nomeando cada handler ativo do mais externo ao mais interno. É mais valioso durante a depuração de problemas de buffer ou antes de registrar um handler (como gzip) que pode já estar presente. Use-a em conjunto com ob_get_level() quando precisar apenas da contagem.

Prática