debug_print_backtrace()

Introdução

Quando um script PHP encontra um erro, saber onde ele está nem sempre é suficiente — você também precisa saber como chegou lá: qual função chamou qual, em que ordem. Essa cadeia de chamadas é a pilha de chamadas, e debug_print_backtrace() a imprime para você, já formatada, diretamente na saída. É a maneira mais rápida de responder "qual caminho levou a esta linha?" sem precisar configurar um depurador completo como o Xdebug.

Este capítulo aborda o que a função faz, seus parâmetros, como ler sua saída, quando utilizá-la e como ela difere de sua função irmã debug_backtrace().

O que debug_print_backtrace() faz

debug_print_backtrace() percorre a pilha de chamadas atual — cada função ou método ativo, desde o script de nível superior até o ponto onde você a chamou — e imprime um rastreamento legível por humanos. Ao contrário de debug_backtrace(), que retorna a pilha como um array para você inspecionar ou registrar, debug_print_backtrace() escreve o texto formatado diretamente na saída padrão e não retorna nada (void).

Use-a quando quiser apenas ver o caminho de chamadas imediatamente. Use debug_backtrace() quando precisar processar a pilha (filtrar quadros, armazená-la, enviá-la para um logger).

Sintaxe

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

Ambos os parâmetros são opcionais:

• $options — uma máscara de bits que ajusta a saída. O único sinalizador é DEBUG_BACKTRACE_IGNORE_ARGS, que omite os ["params"] (argumentos de função) de cada quadro. Passar 0 (o padrão) inclui resumos dos argumentos.
• $limit — limita o número de quadros da pilha impressos. 0 (o padrão) significa sem limite. Útil em recursões profundas quando você só se importa com as chamadas mais recentes. Disponível desde PHP 5.4.0.

Uso Básico

Chame a função de qualquer lugar no seu script. Considere três funções que se chamam em sequência:

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

function b()
{
    c();
}

function c()
{
    debug_print_backtrace();
}

a();
?>

Aqui a() chama b(), que chama c(), que chama debug_print_backtrace(). A saída é uma lista numerada, com a chamada mais recente primeiro:

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

Leia de cima para baixo como "do mais interno ao mais externo": o quadro #0 é onde c() executou (linha 9), #1 é seu chamador b() (linha 4), e #2 é o ponto de chamada original a() (linha 17). Cada linha mostra o arquivo, o número da linha entre parênteses e a função que estava em execução. O ponto de entrada do script em si não é listado como um quadro porque não possui chamador.

Limitando o Número de Quadros

Em código recursivo ou profundamente aninhado, o rastreamento pode ser longo. Passe um $limit para manter apenas os quadros mais próximos:

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

countdown(5);
?>

Apenas dois quadros são impressos, mesmo que countdown() tenha recursado várias vezes:

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

Ocultando Argumentos

Por padrão, cada quadro exibe um resumo dos argumentos passados (como visto acima com countdown(2)). Para dados sensíveis — senhas, tokens — ou simplesmente para reduzir o ruído, passe DEBUG_BACKTRACE_IGNORE_ARGS:

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

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

O quadro ainda aparece, mas a senha não vaza no rastreamento:

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

Quando Usar

• Rastreando chamadas inesperadas — um método executa quando você não esperava; coloque um backtrace no início para ver quem o acionou.
• Entendendo código legado — mapeie rapidamente o fluxo de chamadas sem precisar percorrer um depurador passo a passo.
• Registrando contexto em erros — embora para registro em log, prefira debug_backtrace() para capturar a pilha como string e direcioná-la para um arquivo (veja a nota abaixo).

Armadilhas

• Ela imprime, não retorna. Você não pode atribuir seu resultado a uma variável. Se precisar da pilha para registro, use debug_backtrace().
• A saída vai para a resposta. Em uma requisição web, o rastreamento aparece na saída da página (ou no navegador), o que pode corromper HTML ou JSON. Remova essas chamadas antes de enviar para produção — ou use uma alternativa mais adequada para logs.
• Capturando como string. Se quiser a formatação de debug_print_backtrace() em um log, envolva-a em buffering de saída:

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

Funções Relacionadas

• debug_backtrace() — retorna a pilha de chamadas como um array em vez de imprimi-la.
• var_dump() e print_r() — inspecionam os valores das variáveis durante a depuração.
• error_reporting() — controla quais erros PHP exibe em primeiro lugar.

Conclusão

debug_print_backtrace() é uma forma de uma linha para imprimir a cadeia de chamadas de função que levou ao ponto atual em um script PHP. Seus parâmetros opcionais $options e $limit permitem ocultar argumentos e limitar rastreamentos longos. Lembre-se de que ela imprime em vez de retornar — para acesso programático à pilha, use debug_backtrace(), e remova rastreamentos baseados em impressão antes de implantar em produção.

Prática