getTraceAsString()

Ce que fait getTraceAsString()

getTraceAsString() est une méthode disponible sur toute exception PHP (toute classe qui implémente Throwable — Exception, Error et leurs sous-classes). Elle retourne la trace de la pile — la chaîne d'appels de fonctions et de méthodes actifs au moment où l'exception a été lancée — formatée sous forme d'une seule chaîne lisible par un humain.

La trace de la pile répond à la question « comment l'exécution est-elle arrivée ici ? » Quand quelque chose est lancé en profondeur dans votre code, le message seul (getMessage()) vous dit ce qui s'est mal passé, mais la trace vous indique le chemin exact des appels qui y ont conduit. C'est donc l'information la plus utile pour déboguer une erreur difficile à reproduire.

getTraceAsString() est la version chaîne de getTrace(), qui retourne les mêmes informations sous forme d'un tableau structuré. Utilisez getTrace() quand vous avez besoin d'inspecter des frames individuels par programme ; utilisez getTraceAsString() quand vous voulez simplement quelque chose à journaliser ou afficher.

Syntaxe

public Throwable::getTraceAsString(): string

Elle ne prend aucun argument et est final sur les classes de base Exception et Error, donc elle retourne toujours le format de trace standard de PHP. Vous l'appelez sur un objet exception capturé à l'intérieur d'un bloc catch :

<?php

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

Capturer Throwable (plutôt que seulement Exception) signifie que vous gérez également les objets Error tels que TypeError et DivisionByZeroError. Consultez le chapitre Exception pour la hiérarchie complète.

Un exemple complet et exécutable

Ce script lance une exception à deux niveaux de profondeur pour vous montrer à quoi ressemble réellement la chaîne de trace :

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

Sortie :

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

Lire la sortie

Chaque ligne est un frame dans la pile d'appels, listé du plus interne au plus externe :

• #0, #1, … — le numéro du frame. #0 est l'appel qui était en cours d'exécution quand l'exception a été lancée ; les numéros supérieurs sont les appelants au-dessus.
• /app/index.php(10) — le fichier et le numéro de ligne du site d'appel.
• loadUser(42) — la fonction ou la méthode qui a été appelée, avec ses arguments. Les arguments de type chaîne longue sont tronqués (ex. '/etc/app/missin...') pour garder la trace lisible.
• #2 {main} — le frame final spécial marquant le script de niveau supérieur (la portée globale).

Le site de lancement lui-même (le fichier et la ligne exacts où throw a été exécuté) n'est pas dans cette chaîne — il se trouve dans getFile() et getLine().

Exemples

Exemple 1 : Journaliser la trace dans un fichier

En production, vous voulez rarement montrer une trace à l'utilisateur — vous la journalisez pour une analyse ultérieure. Combinez le message, le fichier et la ligne avec la trace pour un enregistrement complet :

<?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 empêche deux requêtes simultanées d'entrelacer leurs entrées de journal. Pour les vraies applications, une bibliothèque de journalisation telle que Monolog est préférable, mais les données sous-jacentes sont la même chaîne que vous obtenez ici.

Exemple 2 : Afficher la trace dans le navigateur (développement uniquement)

En travaillant localement, il peut être pratique d'afficher la trace directement sur la page. Enveloppez-la dans <pre> pour préserver les sauts de ligne, et échappez-la pour que le contenu de la trace ne puisse pas injecter du HTML :

<?php

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

N'exposez jamais les traces aux utilisateurs finaux en production — elles révèlent des chemins de fichiers, la structure du code et parfois des valeurs d'arguments qui aident les attaquants. Conditionnez ceci à une vérification de l'environnement.

Exemple 3 : Conserver la trace lors des re-lancements

Quand vous capturez une exception de bas niveau et en relancez une plus significative, passez l'originale comme exception précédente pour que sa trace ne soit pas perdue :

<?php

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

La nouvelle RuntimeException a sa propre trace, tandis que getPrevious() vous renvoie l'exception d'origine (et son getTraceAsString()). Le gestionnaire d'exceptions non capturées par défaut de PHP affiche les deux, enchaînées.

Pièges courants

• La trace décrit le point de lancement, pas le point de capture. Elle est fixée au moment où l'exception est construite, donc appeler getTraceAsString() plus tard montre toujours l'origine de l'exception, pas l'endroit où vous l'avez gérée.
• Les arguments peuvent être tronqués ou masqués. Les chaînes longues sont raccourcies ; avec le paramètre INI zend.exception_ignore_args activé (valeur par défaut dans de nombreuses configurations de production), les valeurs des arguments sont entièrement omises pour des raisons de sécurité.
• Elle retourne une chaîne, jamais null. Même pour une exception lancée au niveau supérieur, vous obtenez au moins le frame #0 {main}.

Méthodes associées

• getTrace() — les mêmes données sous forme de tableau structuré.
• getMessage() — le message d'erreur lisible par un humain.
• getCode() — le code numérique de l'exception.
• getPrevious() — l'exception précédente enchaînée.
• set-exception-handler() — gérer les exceptions non capturées globalement.

Conclusion

getTraceAsString() transforme la pile d'appels d'une exception en une chaîne compacte et journalisable, ce qui en fait l'un des outils les plus précieux pour diagnostiquer les erreurs en PHP. Associez-la à getMessage(), getFile() et getLine() pour capturer une image complète de chaque échec, journalisez-la plutôt que de la montrer aux utilisateurs en production, et préservez la chaîne avec getPrevious() chaque fois que vous relancez une exception.

Pratique