Funzione PHP ob_list_handlers(): Tutto quello che devi sapere

La funzione ob_list_handlers() restituisce un array contenente i nomi di ogni handler del buffer di output attualmente attivo, ordinati dal buffer più esterno a quello più interno. Il buffering dell'output consente a PHP di raccogliere l'output generato in memoria anziché inviarlo direttamente al browser; un handler è il callback opzionale che si associa a un buffer tramite ob_start() per trasformare quell'output prima che venga inviato. Questa pagina tratta la sintassi, il valore restituito, come PHP denomina ciascun handler e quando è effettivamente utile ricorrere a ob_list_handlers().

Sintassi

ob_list_handlers(): array

La funzione non accetta argomenti e restituisce un array di stringhe. Quando nessun buffer di output è attivo, restituisce un array vuoto.

Come appaiono i nomi degli handler

Le stringhe restituite non sono il contenuto del buffer — sono etichette che identificano ciascun handler. L'etichetta dipende da come è stato aperto il buffer:

Poiché tutte le funzioni anonime vengono riportate come "Closure::__invoke", non è possibile distinguere due closure diverse tramite questo array — assegna un nome alle funzioni handler se hai bisogno di identificarle in seguito.

Utilizzo di base

Chiama ob_list_handlers() e scorri il risultato. Quando non è attivo alcun buffer l'array è vuoto, quindi gestisci quel caso:

<?php

$handlers = ob_list_handlers();

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

Senza buffer avviati, questo stampa:

No output handlers are active.

Ispezione degli handler annidati

I buffer di output si impilano: ogni ob_start() apre un nuovo buffer sopra il precedente. ob_list_handlers() riflette l'intero stack, risultando utile per vedere esattamente cosa è sovrapposto.

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

Output:

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

L'ordine corrisponde all'ordine in cui i buffer sono stati aperti: l'indice 0 è il buffer più esterno (il primo), e l'ultimo indice è quello più interno (avviato più di recente).

Quando usare questa funzione?

ob_list_handlers() è uno strumento diagnostico, non qualcosa da chiamare nella normale gestione delle richieste. Ricorrivi quando hai bisogno di:

• Debug di "headers already sent" o output inatteso — conferma quali livelli di buffering sono in uso.
• Evitare la doppia compressione — verifica la presenza di "ob_gzhandler" prima di aggiungere il tuo handler gzip, poiché l'impostazione INI zlib.output_compression potrebbe averne già registrato uno.
• Verificare il comportamento di framework o middleware, poiché molti framework aprono i propri buffer e potresti non sapere quanto sia profondo lo stack.

Per contare i buffer attivi invece di nominarli, ob_get_level() restituisce direttamente la profondità:

<?php

ob_start();
ob_start('ob_gzhandler');

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

Output:

2
2

Errori comuni

• Un array vuoto è normale. Un risultato [] significa semplicemente che nessun buffer è aperto — non è un errore.
• Un nome per buffer. Un buffer avviato senza callback appare comunque, come "default output handler"; il nome riflette l'handler, non l'esistenza del buffer.
• I nomi non sono richiamabili. Le stringhe sono solo etichette. Non puoi passare "Closure::__invoke" a ob_start() per ricreare lo stesso handler.

Funzioni correlate

• ob_start() — apre un nuovo buffer di output e associa facoltativamente un handler.
• ob_get_level() — ottiene il livello di annidamento del buffering dell'output.
• ob_get_contents() — legge il contenuto del buffer corrente.
• ob_end_flush() / ob_end_clean() — chiude il buffer più in cima.
• PHP Output Control — panoramica della famiglia di funzioni per il buffering dell'output.

Conclusione

ob_list_handlers() fornisce uno snapshot rapido e in sola lettura dello stack del buffer di output, nominando ciascun handler attivo dal più esterno al più interno. È più utile durante il debug di problemi di buffering o prima di registrare un handler (come gzip) che potrebbe essere già presente. Combinala con ob_get_level() quando hai bisogno solo del conteggio.

Pratica