debug_print_backtrace()

Introducción

Cuando un script PHP llega a un error, saber dónde ocurrió no siempre es suficiente — también necesitas saber cómo llegó hasta allí: qué función llamó a cuál, en qué orden. Esa cadena de llamadas es la pila de llamadas, y debug_print_backtrace() la imprime por ti, ya formateada, directamente en la salida. Es la forma más rápida de responder "¿qué camino llevó a esta línea?" sin necesidad de configurar un depurador completo como Xdebug.

Este capítulo cubre qué hace la función, sus parámetros, cómo leer su salida, cuándo usarla y en qué se diferencia de su función hermana debug_backtrace().

Qué hace debug_print_backtrace()

debug_print_backtrace() recorre la pila de llamadas actual — cada llamada a función o método activa desde el script de nivel superior hasta el punto donde la invocaste — e imprime un rastreo legible por humanos. A diferencia de debug_backtrace(), que devuelve la pila como un array para que la inspecciones o registres, debug_print_backtrace() escribe el texto formateado directamente en la salida estándar y no devuelve nada (void).

Úsala cuando simplemente quieras ver la ruta de llamadas de inmediato. Usa debug_backtrace() cuando necesites procesar la pila (filtrar marcos, almacenarla, enviarla a un logger).

Sintaxis

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

Ambos parámetros son opcionales:

• $options — una máscara de bits que ajusta la salida. El único indicador es DEBUG_BACKTRACE_IGNORE_ARGS, que omite los ["params"] (argumentos de función) de cada marco. Pasar 0 (el valor predeterminado) incluye resúmenes de argumentos.
• $limit — limita el número de marcos de pila impresos. 0 (el valor predeterminado) significa sin límite. Útil en recursiones profundas cuando solo te interesan las pocas llamadas más recientes. Disponible desde PHP 5.4.0.

Uso básico

Llama a la función desde cualquier parte de tu script. Considera tres funciones que se llaman entre sí en secuencia:

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

function b()
{
    c();
}

function c()
{
    debug_print_backtrace();
}

a();
?>

Aquí a() llama a b(), que llama a c(), que llama a debug_print_backtrace(). La salida es una lista numerada, la llamada más reciente primero:

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

Léela de arriba a abajo como "del más interno al más externo": el marco #0 es donde se ejecutó c() (línea 9), #1 es su llamador b() (línea 4) y #2 es el sitio de llamada original a() (línea 17). Cada línea muestra el archivo, el número de línea entre paréntesis y la función que estaba ejecutándose. El punto de entrada del script en sí no aparece como marco porque no tiene llamador.

Limitar el número de marcos

En código recursivo o profundamente anidado el rastreo puede ser extenso. Pasa un $limit para conservar solo los marcos más cercanos:

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

countdown(5);
?>

Solo se imprimen dos marcos aunque countdown() recurrió varias veces:

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

Ocultar argumentos

De forma predeterminada, cada marco muestra un resumen de los argumentos pasados (como se ve arriba con countdown(2)). Para datos sensibles — contraseñas, tokens — o simplemente para reducir el ruido, pasa DEBUG_BACKTRACE_IGNORE_ARGS:

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

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

El marco sigue apareciendo, pero la contraseña ya no se filtra en el rastreo:

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

Cuándo usarla

• Rastrear llamadas inesperadas — un método se ejecuta cuando no lo esperabas; coloca un backtrace al principio para ver quién lo activó.
• Entender código heredado — mapea rápidamente el flujo de llamadas sin necesidad de un depurador paso a paso.
• Registrar contexto en errores — aunque para registrar, es preferible usar debug_backtrace() para poder capturar la pila como string y enrutarla a un archivo (consulta la nota a continuación).

Consideraciones importantes

• Imprime, no devuelve. No puedes asignar su resultado a una variable. Si necesitas la pila para el registro, usa debug_backtrace() en su lugar.
• La salida va a la respuesta. En una solicitud web el rastreo aparece en la salida de la página (o en el navegador), lo que puede corromper HTML o JSON. Elimina estas llamadas antes de desplegar a producción — o usa una alternativa compatible con el registro.
• Capturarlo como string. Si deseas el formato de debug_print_backtrace() en un log, envuélvelo en búfer de salida:

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

Funciones relacionadas

• debug_backtrace() — devuelve la pila de llamadas como un array en lugar de imprimirla.
• var_dump() y print_r() — inspeccionan los valores de las variables durante la depuración.
• error_reporting() — controla qué errores muestra PHP en primer lugar.

Conclusión

debug_print_backtrace() es una forma de una sola línea para imprimir la cadena de llamadas a funciones que llevó al punto actual en un script PHP. Sus parámetros opcionales $options y $limit permiten ocultar argumentos y recortar rastreos extensos. Recuerda que imprime en lugar de devolver — para acceso programático a la pila, usa debug_backtrace(), y elimina los rastreos basados en impresión antes de desplegar a producción.

Práctica