debug_backtrace()

Cuando un error aparece profundamente dentro de llamadas a funciones anidadas, el mensaje de error por sí solo rara vez te indica cómo llegó el código hasta allí. La función debug_backtrace() responde esa pregunta: devuelve una instantánea de la pila de llamadas en el punto exacto donde la invocas, para que puedas ver qué función llamó a cuál, en qué archivo y en qué línea. Esta página explica la firma de la función, la estructura del array que devuelve, patrones prácticos para utilizarla y cómo encaja junto a las herramientas de reporte de errores de PHP.

Qué devuelve debug_backtrace()

debug_backtrace() devuelve un array de arrays asociativos — un elemento por cada marco de la pila, ordenado desde la llamada más interna (donde la invocaste) hacia el punto de entrada del script. Nunca lanza excepciones ni detiene la ejecución; simplemente reporta la pila actual.

La firma es:

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

Parámetros

• $options (int) — una máscara de bits que controla qué incluye cada marco:
  • DEBUG_BACKTRACE_PROVIDE_OBJECT (predeterminado) — incluye el object real en las llamadas a métodos.
  • DEBUG_BACKTRACE_IGNORE_ARGS — omite el índice args, lo que mantiene la salida pequeña y evita mantener referencias a argumentos de gran tamaño.
• $limit (int) — el número máximo de marcos a devolver. 0 (el predeterminado) significa la pila completa. Útil cuando solo necesitas el llamador inmediato.

Cada marco

Cada marco es un array asociativo que puede contener:

• function — el nombre de la función o método llamado.
• line — la línea desde la que se realizó la llamada.
• file — el archivo desde el que se realizó la llamada.
• class — el nombre de la clase, en llamadas a métodos.
• object — la instancia del object, cuando DEBUG_BACKTRACE_PROVIDE_OBJECT está activo.
• type — -> para llamadas de instancia, :: para llamadas estáticas, ausente para funciones simples.
• args — los argumentos pasados a la llamada (a menos que se use DEBUG_BACKTRACE_IGNORE_ARGS).

Ejemplo básico: rastrear la pila de llamadas

Este script recorre tres funciones anidadas e imprime un rastreo legible desde la más 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();

Salida:

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

El marco #0 es donde se llamó a debug_backtrace(), y cada marco siguiente es el llamador por encima de él. Usa print_r($trace) en lugar del bucle si quieres ver todas las claves (file, args, etc.) de una sola vez.

Encontrar el llamador

Un uso habitual y concreto es averiguar quién llamó a la función actual — para registrar eventos o emitir avisos de obsolescencia. Pasa DEBUG_BACKTRACE_IGNORE_ARGS para mantener el resultado liviano y 2 como límite; luego lee el índice de marco 1 (el índice 0 es la función actual):

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

Salida:

Called by doWork() on line 11

El guard ?? null es importante cuando logCaller() se invoca desde el nivel superior, donde no existe el marco 1.

Cuándo usarla

• Registro y diagnóstico — adjunta un rastreo a una entrada de log para reconstruir cómo se alcanzó un estado inesperado.
• Avisos de obsolescencia — reporta el llamador exacto de una función que estás eliminando gradualmente.
• Manejadores de errores personalizados — enriquece un callback de set_error_handler() con la pila de llamadas circundante.
• Comprender el flujo de un framework — ve qué middleware o hook condujo a tu código.

Advertencias

• Rendimiento y memoria. Con las opciones predeterminadas, cada marco conserva referencias de args y object, lo que puede ser pesado. En rutas de ejecución frecuente o cuando los argumentos son grandes, pasa DEBUG_BACKTRACE_IGNORE_ARGS.
• Código en producción. Trata debug_backtrace() como una herramienta de depuración. No la dejes imprimiendo en la salida en producción — redirige la salida a un log.
• ¿Solo necesitas una impresión? Usa debug_print_backtrace(), que muestra directamente un rastreo formateado sin devolver un array.
• ¿Dentro de una excepción? El object Exception lanzado ya lleva su rastreo mediante $e->getTrace() y $e->getTraceAsString().

Tipos de errores de PHP de un vistazo

debug_backtrace() es más útil cuando ya sabes que ocurrió un error y quieres contexto. Los errores de PHP se dividen en unas pocas categorías generales:

• Errores de análisis (sintaxis) — código inválido que el analizador rechaza antes de la ejecución, como un punto y coma faltante o una llave sin cerrar. Son fatales.
• Errores lógicos — el código se ejecuta pero produce un resultado incorrecto; no hay mensaje de error, que es exactamente cuando un backtrace ayuda.
• Errores en tiempo de ejecución — se producen mientras el script se ejecuta, desde avisos y advertencias no fatales (variable indefinida, include faltante, advertencias de división) hasta errores fatales (llamar a un método sobre un non-object, superar el límite de memoria) que detienen la ejecución.

Para controlar cuáles de estos ves, establece el nivel con error_reporting(). Durante el desarrollo, habilita todos:

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

Temas relacionados

• debug_print_backtrace() — imprime un backtrace formateado.
• error_reporting() — elige qué errores se reportan.
• trigger_error() — genera tus propios errores.
• PHP Exceptions — manejo estructurado de errores con try/catch.

Práctica