debug_backtrace()

Quando um bug aparece no fundo de chamadas de função aninhadas, a mensagem de erro raramente diz como o código chegou até lá. A função debug_backtrace() responde a essa pergunta: ela retorna um instantâneo da pilha de chamadas no ponto exato em que você a invoca, permitindo ver qual função chamou qual, em qual arquivo e em qual linha. Esta página explica a assinatura da função, a estrutura do array que ela retorna, padrões práticos de uso e como ela se encaixa junto às ferramentas de relatório de erros do PHP.

O que debug_backtrace() retorna

debug_backtrace() retorna um array de arrays associativos — um elemento por frame de pilha, ordenado do ponto de chamada mais interno (onde você a invocou) para o ponto de entrada do script. Ela nunca lança exceções e nunca interrompe a execução; apenas reporta a pilha atual.

A assinatura é:

debug_backtrace(int $options = DEBUG_BACKTRACE_PROVIDE_OBJECT, int $limit = 0): array

Parâmetros

• $options (int) — uma máscara de bits que controla o que cada frame inclui:
  • DEBUG_BACKTRACE_PROVIDE_OBJECT (padrão) — inclui o object real para chamadas de método.
  • DEBUG_BACKTRACE_IGNORE_ARGS — omite o índice args, mantendo a saída pequena e evitando referências a argumentos volumosos.
• $limit (int) — o número máximo de frames a retornar. 0 (padrão) significa a pilha inteira. Útil quando você precisa apenas do chamador imediato.

Cada frame

Cada frame é um array associativo que pode conter:

• function — o nome da função ou método chamado.
• line — a linha de onde a chamada foi feita.
• file — o arquivo de onde a chamada foi feita.
• class — o nome da classe, para chamadas de método.
• object — a instância do object, quando DEBUG_BACKTRACE_PROVIDE_OBJECT está definido.
• type — -> para chamadas de instância, :: para chamadas estáticas, ausente para funções simples.
• args — os argumentos passados para a chamada (a menos que DEBUG_BACKTRACE_IGNORE_ARGS seja usado).

Exemplo básico: rastreando a pilha de chamadas

Este script percorre três funções aninhadas e imprime um rastreamento legível a partir da mais profunda:

<?php
function levelThree() {
    $trace = debug_backtrace();
    foreach ($trace as $i => $frame) {
        echo "#$i {$frame['function']}() at line {$frame['line']}\n";
    }
}
function levelTwo() { levelThree(); }
function levelOne() { levelTwo(); }
levelOne();

Saída:

#0 levelThree() at line 8
#1 levelTwo() at line 9
#2 levelOne() at line 10

O frame #0 é onde debug_backtrace() foi chamada, e cada frame subsequente é o chamador acima dele. Use print_r($trace) em vez do loop se quiser ver todas as chaves (file, args e assim por diante) de uma só vez.

Encontrando o chamador

Um uso comum e focado é descobrir quem chamou a função atual — para logging ou avisos de depreciação. Passe DEBUG_BACKTRACE_IGNORE_ARGS para manter o resultado leve e 2 como limite; depois leia o índice de frame 1 (o índice 0 é a função atual):

<?php
function logCaller() {
    $caller = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 2)[1] ?? null;
    if ($caller) {
        echo "Called by {$caller['function']}() on line {$caller['line']}\n";
    }
}
function doWork() {
    logCaller();
}
doWork();

Saída:

Called by doWork() on line 11

A proteção ?? null é importante quando logCaller() é invocada a partir do nível superior, onde não existe o frame 1.

Quando usar

• Logging e diagnósticos — anexe um rastreamento a uma entrada de log para reconstruir como um estado inesperado foi alcançado.
• Avisos de depreciação — informe o chamador exato de uma função que está sendo descontinuada.
• Handlers de erro personalizados — enriqueça um callback de set_error_handler() com a pilha de chamadas ao redor.
• Entendendo o fluxo de frameworks — veja qual middleware ou hook levou ao seu código.

Armadilhas

• Desempenho e memória. Com as opções padrão, cada frame mantém referências a args e object, o que pode ser pesado. Em caminhos críticos de desempenho ou quando os argumentos são grandes, passe DEBUG_BACKTRACE_IGNORE_ARGS.
• Código em produção. Trate debug_backtrace() como uma ferramenta de depuração. Não a deixe imprimindo na saída em produção — redirecione para um log.
• Só precisa de uma saída impressa? Use debug_print_backtrace(), que ecoa um rastreamento formatado diretamente sem retornar um array.
• Dentro de uma exceção? O objeto Exception lançado já carrega seu rastreamento via $e->getTrace() e $e->getTraceAsString().

Tipos de erro do PHP em resumo

debug_backtrace() é mais útil quando você já sabe que um erro ocorreu e deseja contexto. Os erros do PHP se enquadram em algumas categorias amplas:

• Erros de parse (sintaxe) — código inválido que o parser rejeita antes da execução, como um ponto e vírgula ausente ou chave sem par. Esses são fatais.
• Erros lógicos — o código executa, mas produz o resultado errado; não há mensagem de erro, o que é exatamente quando um backtrace ajuda.
• Erros de runtime — levantados durante a execução do script, variando de notices e warnings não fatais (variável indefinida, include ausente, avisos de divisão) a erros fatais (chamar um método em um não-object, exceder o limite de memória) que interrompem a execução.

Para controlar quais desses você vê, defina o nível com error_reporting(). Durante o desenvolvimento, habilite tudo:

<?php
// Report all errors, notices and warnings, and show them
error_reporting(E_ALL);
ini_set('display_errors', '1');

graph TD;
    A[PHP Error] -->|invalid code| B(Parse / Syntax)
    A -->|wrong result| C(Logical)
    A -->|while running| D(Runtime)
    D --> E(Notice / Warning)
    D --> F(Fatal Error)

Tópicos relacionados

• debug_print_backtrace() — imprime um backtrace formatado.
• error_reporting() — escolhe quais erros são reportados.
• trigger_error() — levanta seus próprios erros.
• PHP Exceptions — tratamento estruturado de erros com try/catch.

Prática