getTrace()

PHP getTrace()

Exception::getTrace() retourne la trace de la pile d'une exception sous forme de tableau. Chaque élément décrit un appel de fonction ou de méthode qui se trouvait dans la pile au moment où l'exception a été lancée, ordonné du point de lancement vers l'appelant externe. C'est l'un des outils les plus utiles pour déterminer où et comment une erreur s'est produite.

Cette page explique ce que retourne getTrace(), la structure de chaque frame de trace, et comment elle diffère du plus familier getTraceAsString(). La méthode est définie sur l'interface de base Throwable, elle est donc disponible sur chaque objet Exception et Error.

public Exception::getTrace(): array

Elle ne prend aucun argument et retourne un tableau indexé. La frame 0 est l'appel le plus interne (la fonction qui a effectivement lancé l'exception), et les index croissent vers l'appelant le plus externe.

Exemple rapide

Le script suivant lance une exception depuis un appel imbriqué et affiche chaque frame de la trace :

<?php

function readConfig($path) {
    return parseFile($path);
}

function parseFile($path) {
    throw new Exception("Cannot read file: $path");
}

try {
    readConfig('/etc/app.conf');
} catch (Exception $e) {
    $trace = $e->getTrace();
    echo "Number of frames: " . count($trace) . "\n";
    foreach ($trace as $i => $frame) {
        echo "#$i {$frame['function']}() called in {$frame['file']} on line {$frame['line']}\n";
    }
}

Sortie :

Number of frames: 2
#0 parseFile() called in /path/to/script.php on line 4
#1 readConfig() called in /path/to/script.php on line 12

Remarquez que la frame de la fonction qui a lancé l'exception (parseFile) indique la ligne où elle a été appelée (ligne 4, à l'intérieur de readConfig), et non la ligne du throw lui-même. La ligne du lancement est disponible séparément via getLine() et getFile().

Ce que contient chaque frame de trace

Chaque frame est un tableau associatif. Les clés les plus utiles sont :

Ce script inspecte une seule frame en entier :

<?php

function divide($a, $b) {
    if ($b === 0) {
        throw new InvalidArgumentException('Division by zero');
    }
    return $a / $b;
}

try {
    divide(10, 0);
} catch (Exception $e) {
    print_r($e->getTrace()[0]);
}

Sortie :

Array
(
    [file] => /path/to/script.php
    [line] => 11
    [function] => divide
    [args] => Array
        (
            [0] => 10
            [1] => 0
        )

)

Note de sécurité : l'entrée args contient les valeurs réelles des arguments, qui peuvent inclure des mots de passe, des jetons ou d'autres données sensibles. N'exposez jamais un tableau getTrace() brut aux utilisateurs finaux — consignez-le côté serveur à la place. Le paramètre INI zend.exception_ignore_args de PHP (activé par défaut depuis PHP 7.4) supprime args pour éviter les fuites de données sensibles ; si vous ne voyez pas de clé args, c'est la raison.

getTrace() vs getTraceAsString()

getTrace() vous donne le tableau brut afin que vous puissiez le formater, filtrer ou sérialiser comme vous le souhaitez. Si vous voulez simplement une chaîne lisible par un humain, utilisez getTraceAsString() à la place, qui retourne les mêmes informations pré-formatées :

<?php

try {
    throw new RuntimeException('Something broke');
} catch (Throwable $e) {
    echo $e->getTraceAsString();
}

Utilisez la forme tableau lorsque vous souhaitez parcourir les frames par programme (par exemple, créer un rapport d'erreur personnalisé ou envoyer des données structurées à un service de journalisation), et la forme chaîne pour un affichage rapide ou des lignes de journal.

La place de getTrace() dans l'API des exceptions

getTrace() est l'un des plusieurs accesseurs en lecture seule disponibles sur chaque exception. Ils sont les plus puissants lorsqu'ils sont utilisés ensemble dans un bloc catch :

• getMessage() — le message d'erreur lisible par un humain.
• getCode() — le code d'erreur numérique.
• getFile() et getLine() — où l'exception a été lancée.
• getTraceAsString() — la trace sous forme de chaîne.
• getPrevious() — l'exception chaînée, le cas échéant.

Pour une vue d'ensemble du lancement et de la capture, voir throw, try, et la classe Exception.

Meilleures pratiques pour la gestion des exceptions en PHP

Pour garantir que votre code est maintenable et facile à déboguer, il est important de suivre les meilleures pratiques lors de la gestion des exceptions en PHP. Voici quelques conseils à garder à l'esprit :

1. Utilisez des messages d'exception significatifs.

Lorsque vous lancez une exception, assurez-vous que le message est informatif et utile. Il doit expliquer ce qui s'est mal passé et comment y remédier. Par exemple :

<?php

if ($someCondition) {
  throw new Exception('Invalid input: the email address is not valid.');
}

2. Capturez uniquement les exceptions que vous pouvez gérer.

Lors de la capture d'exceptions, il est important de ne capturer que celles que vous pouvez gérer. Si vous capturez une exception que vous ne pouvez pas gérer, vous risquez de masquer le vrai problème et de rendre le débogage plus difficile. Par exemple :

<?php

try {
  // Some code that may throw an exception.
} catch (InvalidArgumentException $e) {
  // Handle the invalid argument exception.
} catch (Exception $e) {
  // Handle all other exceptions.
}

3. Journalisez les exceptions.

La journalisation des exceptions peut vous aider à diagnostiquer les problèmes et à résoudre les incidents. Il est conseillé de journaliser les exceptions dans un fichier ou une base de données afin de pouvoir les consulter ultérieurement. Par exemple :

<?php

try {
  // Some code that may throw an exception.
} catch (Exception $e) {
  error_log($e->getMessage(), 0);
}

4. Utilisez des hiérarchies d'exceptions.

L'utilisation de hiérarchies d'exceptions peut vous aider à organiser votre code et à faciliter la capture de types d'exceptions spécifiques. Par exemple, vous pourriez créer une classe DatabaseException qui étend la classe Exception, puis lancer cette exception lorsqu'une erreur de base de données se produit. Vous pourriez alors capturer uniquement les instances de DatabaseException lors du traitement des erreurs de base de données.

Conclusion

La gestion des exceptions est un aspect essentiel de la programmation PHP, et la méthode getTrace() est un outil précieux pour déboguer et résoudre les exceptions. En retournant une trace d'exécution du contexte, vous pouvez identifier précisément où une exception s'est produite et comment elle a été déclenchée.

Dans ce guide, nous avons couvert les bases de la gestion des exceptions en PHP, notamment comment lancer et capturer des exceptions, ainsi que les meilleures pratiques pour utiliser les exceptions efficacement. Nous avons également exploré la méthode getTrace() et comment elle peut vous aider à diagnostiquer et corriger les erreurs dans votre code.

En suivant ces meilleures pratiques et en tirant parti de la méthode getTrace(), vous pouvez écrire du code PHP robuste, fiable et facile à maintenir. La gestion des exceptions peut sembler un détail mineur, mais elle peut faire une grande différence dans la qualité et la convivialité de votre code.

Practice