getTraceAsString()

Qué hace getTraceAsString()

getTraceAsString() es un método disponible en todas las excepciones de PHP (cualquier clase que implemente Throwable — Exception, Error y sus subclases). Devuelve el seguimiento de pila — la cadena de llamadas a funciones y métodos que estaban activas en el momento en que se lanzó la excepción — formateado como una sola cadena legible por humanos.

El seguimiento de pila responde a la pregunta "¿cómo llegó la ejecución aquí?" Cuando algo se lanza en lo profundo de tu código, el mensaje por sí solo (getMessage()) te dice qué salió mal, pero el seguimiento te indica la ruta exacta de llamadas que lo originó. Eso lo convierte en la información más útil al depurar un error que no puedes reproducir fácilmente.

getTraceAsString() es la versión en string de getTrace(), que devuelve la misma información como un array estructurado. Usa getTrace() cuando necesites inspeccionar fotogramas individuales mediante programación; usa getTraceAsString() cuando simplemente quieras algo para registrar o imprimir.

Sintaxis

public Throwable::getTraceAsString(): string

No toma argumentos y es final en las clases base Exception y Error, por lo que siempre devuelve el formato de seguimiento estándar de PHP. Se llama sobre un objeto de excepción capturado dentro de un bloque catch:

<?php

try {
    // Code that may throw an exception
} catch (Throwable $e) {
    $trace = $e->getTraceAsString();
}

Capturar Throwable (en lugar de solo Exception) significa que también manejas objetos Error como TypeError y DivisionByZeroError. Consulta el capítulo Exception para la jerarquía completa.

Un ejemplo completo y ejecutable

Este script lanza una excepción dos niveles de profundidad para que puedas ver cómo luce realmente la cadena de seguimiento:

<?php

function loadUser(int $id): array
{
    throw new InvalidArgumentException("No user with id $id");
}

function handleRequest(): void
{
    loadUser(42);
}

try {
    handleRequest();
} catch (Throwable $e) {
    echo $e->getTraceAsString();
}

Salida:

#0 /app/index.php(10): loadUser(42)
#1 /app/index.php(14): handleRequest()
#2 {main}

Cómo leer la salida

Cada línea es un fotograma en la pila de llamadas, listados desde el más interno hacia afuera:

• #0, #1, … — el número de fotograma. #0 es la llamada que se estaba ejecutando cuando se lanzó la excepción; los números más altos son los llamadores por encima de ella.
• /app/index.php(10) — el archivo y número de línea del lugar de la llamada.
• loadUser(42) — la función o método que fue llamado, con sus argumentos. Los argumentos de cadena largos se truncan (p. ej. '/etc/app/missin...') para mantener el seguimiento legible.
• #2 {main} — el fotograma final especial que marca el script de nivel superior (el ámbito global).

El lugar donde se lanza (el archivo y línea exactos donde se ejecutó throw) no aparece en esta cadena — se encuentra en getFile() y getLine().

Ejemplos

Ejemplo 1: Registrar el seguimiento en un archivo

En producción rara vez querrás mostrar un seguimiento al usuario — lo registras para análisis posterior. Combina el mensaje, el archivo y la línea con el seguimiento para obtener un registro completo:

<?php

try {
    // Code that may throw an exception
} catch (Throwable $e) {
    $entry = sprintf(
        "[%s] %s in %s:%d\n%s\n\n",
        date('Y-m-d H:i:s'),
        $e->getMessage(),
        $e->getFile(),
        $e->getLine(),
        $e->getTraceAsString()
    );

    file_put_contents('/path/to/app.log', $entry, FILE_APPEND | LOCK_EX);
}

LOCK_EX evita que dos solicitudes simultáneas intercalen sus entradas de registro. Para aplicaciones reales es preferible una biblioteca de registro como Monolog, pero los datos subyacentes son la misma cadena que obtienes aquí.

Ejemplo 2: Mostrar el seguimiento en el navegador (solo en desarrollo)

Al trabajar localmente puede ser útil imprimir el seguimiento directamente en la página. Envuélvelo en <pre> para que se preserven los saltos de línea, y escápalo para que el contenido del seguimiento no pueda inyectar HTML:

<?php

try {
    // Code that may throw an exception
} catch (Throwable $e) {
    echo '<pre>' . htmlspecialchars($e->getTraceAsString()) . '</pre>';
}

Nunca expongas seguimientos a los usuarios finales en producción — revelan rutas de archivos, estructura del código y a veces valores de argumentos que ayudan a los atacantes. Protege esto con una verificación de entorno.

Ejemplo 3: Preservar el seguimiento al relanzar excepciones

Cuando capturas una excepción de bajo nivel y relanzas una más significativa, pasa la original como la excepción anterior para que su seguimiento no se pierda:

<?php

try {
    // some database call that throws PDOException
} catch (PDOException $e) {
    throw new RuntimeException('Could not load the report', 0, $e);
}

La nueva RuntimeException tiene su propio seguimiento, mientras que getPrevious() te devuelve la excepción original (y su getTraceAsString()). El manejador de excepciones no capturadas predeterminado de PHP imprime ambas, encadenadas.

Errores comunes

• El seguimiento describe el punto de lanzamiento, no el punto de captura. Queda fijado en el momento en que se construye la excepción, por lo que llamar a getTraceAsString() más tarde todavía muestra dónde se originó la excepción, no dónde la manejaste.
• Los argumentos pueden truncarse u ocultarse. Las cadenas largas se acortan; con la configuración INI zend.exception_ignore_args habilitada (predeterminada en muchas configuraciones de producción), los valores de los argumentos se omiten por completo por razones de seguridad.
• Devuelve una cadena, nunca null. Incluso para una excepción lanzada en el nivel superior obtienes al menos el fotograma #0 {main}.

Métodos relacionados

• getTrace() — los mismos datos como array estructurado.
• getMessage() — el mensaje de error legible por humanos.
• getCode() — el código numérico de la excepción.
• getPrevious() — la excepción anterior encadenada.
• set-exception-handler() — maneja las excepciones no capturadas globalmente.

Conclusión

getTraceAsString() convierte la pila de llamadas de una excepción en una cadena compacta y registrable, lo que la convierte en una de las herramientas más valiosas para diagnosticar errores en PHP. Combínala con getMessage(), getFile() y getLine() para capturar una imagen completa de cada fallo, regístrala en lugar de mostrarla a los usuarios en producción, y preserva la cadena con getPrevious() siempre que relances una excepción.

Práctica