debug_print_backtrace()

Introduction

Lorsqu'un script PHP atteint une erreur, savoir où elle se trouve n'est pas toujours suffisant — vous devez aussi savoir comment il y est arrivé : quelle fonction a appelé laquelle, dans quel ordre. Cette chaîne d'appels constitue la pile d'appels, et debug_print_backtrace() l'affiche pour vous, formatée et prête à l'emploi, directement en sortie. C'est le moyen le plus rapide de répondre à la question « quel chemin a mené à cette ligne ? » sans configurer un débogueur complet comme Xdebug.

Ce chapitre explique ce que fait la fonction, ses paramètres, comment lire sa sortie, quand l'utiliser, et en quoi elle diffère de sa fonction sœur debug_backtrace().

Ce que fait debug_print_backtrace()

debug_print_backtrace() parcourt la pile d'appels courante — chaque appel de fonction ou de méthode actif depuis le script de niveau supérieur jusqu'à l'endroit où vous l'avez appelée — et affiche une trace lisible par un humain. Contrairement à debug_backtrace(), qui retourne la pile sous forme d'array pour que vous puissiez l'inspecter ou la journaliser, debug_print_backtrace() écrit le texte formaté directement en sortie standard et ne retourne rien (void).

Utilisez-la lorsque vous souhaitez simplement voir le chemin d'appel immédiatement. Utilisez debug_backtrace() lorsque vous devez traiter la pile (filtrer les frames, la stocker, l'envoyer à un logger).

Syntaxe

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

Les deux paramètres sont optionnels :

• $options — un masque de bits qui ajuste la sortie. Le seul indicateur disponible est DEBUG_BACKTRACE_IGNORE_ARGS, qui omet les ["params"] (arguments de fonction) de chaque frame. Passer 0 (valeur par défaut) inclut les résumés des arguments.
• $limit — limite le nombre de frames de la pile affichées. 0 (valeur par défaut) signifie aucune limite. Utile dans les récursions profondes lorsque vous ne vous intéressez qu'aux quelques appels les plus récents. Disponible depuis PHP 5.4.0.

Utilisation de base

Appelez la fonction depuis n'importe quel endroit de votre script. Considérons trois fonctions qui s'appellent mutuellement en séquence :

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

function b()
{
    c();
}

function c()
{
    debug_print_backtrace();
}

a();
?>

Ici, a() appelle b(), qui appelle c(), qui appelle debug_print_backtrace(). La sortie est une liste numérotée, l'appel le plus récent en premier :

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

Lisez-la de haut en bas comme « du plus interne au plus externe » : la frame #0 correspond à l'endroit où c() s'est exécutée (ligne 9), #1 est son appelante b() (ligne 4), et #2 est le site d'appel original a() (ligne 17). Chaque ligne indique le fichier, le numéro de ligne entre parenthèses, et la fonction qui s'exécutait. Le point d'entrée du script lui-même n'apparaît pas comme une frame, car il n'a pas d'appelant.

Limiter le nombre de frames

Dans du code récursif ou profondément imbriqué, la trace peut être longue. Passez un $limit pour ne conserver que les frames les plus proches :

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

countdown(5);
?>

Seules deux frames sont affichées, même si countdown() a récursé plusieurs fois :

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

Masquer les arguments

Par défaut, chaque frame affiche un résumé des arguments passés (comme vu ci-dessus avec countdown(2)). Pour les données sensibles — mots de passe, tokens — ou simplement pour réduire le bruit, passez DEBUG_BACKTRACE_IGNORE_ARGS :

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

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

La frame apparaît toujours, mais le mot de passe ne fuite plus dans la trace :

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

Quand l'utiliser

• Tracer des appels inattendus — une méthode s'exécute sans que vous ne l'attendiez ; placez une trace en tête pour voir qui l'a déclenchée.
• Comprendre du code existant — cartographiez rapidement le flux d'appels sans passer par un débogueur.
• Journaliser le contexte lors des erreurs — bien que pour la journalisation, il soit préférable d'utiliser debug_backtrace() afin de capturer la pile sous forme de string et de la router vers un fichier (voir la remarque ci-dessous).

Points d'attention

• Elle affiche, elle ne retourne pas. Vous ne pouvez pas assigner son résultat à une variable. Si vous avez besoin de la pile pour la journalisation, utilisez debug_backtrace() à la place.
• La sortie va dans la réponse. Lors d'une requête web, la trace arrive dans la sortie de la page (ou du navigateur), ce qui peut corrompre le HTML ou le JSON. Supprimez ces appels avant de déployer en production — ou utilisez une alternative adaptée à la journalisation.
• Capturer la trace sous forme de string. Si vous souhaitez utiliser le formatage de debug_print_backtrace() dans un log, encapsulez-le dans la mise en tampon de sortie :

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

Fonctions associées

• debug_backtrace() — retourne la pile d'appels sous forme d'array au lieu de l'afficher.
• var_dump() et print_r() — inspectent les valeurs des variables lors du débogage.
• error_reporting() — contrôle les erreurs que PHP remonte en premier lieu.

Conclusion

debug_print_backtrace() est un moyen en une ligne d'afficher la chaîne d'appels de fonctions qui a mené au point courant d'un script PHP. Ses paramètres optionnels $options et $limit permettent de masquer les arguments et de réduire les traces longues. N'oubliez pas qu'elle affiche plutôt qu'elle ne retourne — pour un accès programmatique à la pile, utilisez debug_backtrace(), et supprimez les traces basées sur l'affichage avant de déployer en production.

Pratique