debug_print_backtrace()

Introduzione

Quando uno script PHP raggiunge un errore, sapere dove si trova non è sempre sufficiente — devi anche sapere come ci è arrivato: quale funzione ha chiamato quale, in quale ordine. Quella catena di chiamate è lo stack delle chiamate (call stack), e debug_print_backtrace() lo stampa per te, già formattato, direttamente nell'output. È il modo più rapido per rispondere alla domanda "quale percorso ha portato a questa riga?" senza dover configurare un debugger completo come Xdebug.

Questo capitolo spiega cosa fa la funzione, i suoi parametri, come interpretarne l'output, quando utilizzarla e come si differenzia dalla funzione correlata debug_backtrace().

Cosa fa debug_print_backtrace()

debug_print_backtrace() percorre lo stack delle chiamate corrente — ogni chiamata di funzione o metodo attiva, dallo script di primo livello fino al punto in cui l'hai invocata — e stampa una traccia leggibile dall'utente. A differenza di debug_backtrace(), che restituisce lo stack come array per ispezionarlo o registrarlo, debug_print_backtrace() scrive il testo formattato direttamente sull'output standard e non restituisce nulla (void).

Usala quando vuoi semplicemente vedere il percorso delle chiamate immediatamente. Usa debug_backtrace() quando devi elaborare lo stack (filtrare i frame, memorizzarlo, inviarlo a un logger).

Sintassi

debug_print_backtrace(int $options = 0, int $limit = 0): void

Entrambi i parametri sono opzionali:

• $options — una maschera di bit che modifica l'output. L'unico flag disponibile è DEBUG_BACKTRACE_IGNORE_ARGS, che omette ["params"] (gli argomenti della funzione) da ogni frame. Passare 0 (il valore predefinito) include i riepiloghi degli argomenti.
• $limit — limita il numero di frame dello stack stampati. 0 (il valore predefinito) significa nessun limite. Utile in presenza di ricorsione profonda quando ti interessa solo esaminare le chiamate più recenti. Disponibile da PHP 5.4.0.

Utilizzo di base

Chiama la funzione da qualsiasi punto dello script. Considera tre funzioni che si chiamano l'una con l'altra in sequenza:

<?php
function a()
{
    b();
}

function b()
{
    c();
}

function c()
{
    debug_print_backtrace();
}

a();
?>

Qui a() chiama b(), che chiama c(), che chiama debug_print_backtrace(). L'output è un elenco numerato, dalla chiamata più recente alla prima:

#0 /path/to/script.php(9): c()
#1 /path/to/script.php(4): b()
#2 /path/to/script.php(17): a()

Leggilo dall'alto in basso come "dalla più interna alla più esterna": il frame #0 indica dove c() è stata eseguita (riga 9), #1 è il suo chiamante b() (riga 4), e #2 è il sito di chiamata originale a() (riga 17). Ogni riga mostra il file, il numero di riga tra parentesi e la funzione in esecuzione. Il punto di ingresso dello script non viene elencato come frame perché non ha un chiamante.

Limitare il numero di frame

In codice ricorsivo o profondamente annidato, la traccia può diventare lunga. Passa un $limit per mantenere solo i frame più recenti:

<?php
function countdown($n)
{
    if ($n === 2) {
        // Print just the two nearest frames.
        debug_print_backtrace(0, 2);
        return;
    }
    countdown($n - 1);
}

countdown(5);
?>

Vengono stampati solo due frame anche se countdown() ha ricorso più volte:

#0 /path/to/script.php(9): countdown(2)
#1 /path/to/script.php(9): countdown(3)

Nascondere gli argomenti

Per impostazione predefinita ogni frame mostra un riepilogo degli argomenti passati (come visto sopra con countdown(2)). Per dati sensibili — password, token — o semplicemente per ridurre il rumore, passa DEBUG_BACKTRACE_IGNORE_ARGS:

<?php
function login($user, $password)
{
    debug_print_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS);
}

login('admin', 'secret');
?>

Il frame viene comunque mostrato, ma la password non compare più nella traccia:

#0 /path/to/script.php(7): login()

Quando usarla

• Tracciare chiamate inattese — un metodo viene eseguito quando non te lo aspettavi; inserisci un backtrace all'inizio per vedere chi l'ha attivato.
• Comprendere il codice legacy — mappa rapidamente il flusso delle chiamate senza dover eseguire il codice passo dopo passo con un debugger.
• Registrare il contesto in caso di errori — anche se per il logging è preferibile usare debug_backtrace(), così puoi catturare lo stack come stringa e scriverlo su file (vedi la nota di seguito).

Avvertenze

• Stampa, non restituisce. Non puoi assegnare il suo risultato a una variabile. Se hai bisogno dello stack per il logging, usa debug_backtrace().
• L'output va nella risposta. In una richiesta web la traccia finisce nell'output della pagina (o nel browser), il che può corrompere HTML o JSON. Rimuovi queste chiamate prima di andare in produzione — oppure usa un'alternativa compatibile con il logging.
• Catturare l'output come stringa. Se vuoi la formattazione di debug_print_backtrace() in un log, racchiudila nell'output buffering:

<?php
function handler()
{
    ob_start();
    debug_print_backtrace();
    $trace = ob_get_clean();
    // $trace now holds the formatted backtrace as a string.
    error_log($trace);
}

handler();
?>

Funzioni correlate

• debug_backtrace() — restituisce lo stack delle chiamate come array invece di stamparlo.
• var_dump() e print_r() — ispezionano i valori delle variabili durante il debug.
• error_reporting() — controlla quali errori PHP mostra in primo luogo.

Conclusione

debug_print_backtrace() è un modo immediato, in una sola riga, per stampare la catena di chiamate di funzione che ha portato al punto corrente in uno script PHP. I parametri opzionali $options e $limit permettono di nascondere gli argomenti e ridurre le tracce lunghe. Ricorda che stampa invece di restituire — per accedere programmaticamente allo stack usa debug_backtrace(), e rimuovi le tracce di stampa prima di distribuire in produzione.

Pratica