debug_backtrace() - Apprendre PHP

Lorsqu'un bug apparaît au cœur d'appels de fonctions imbriqués, le message d'erreur seul ne vous dit rarement comment le code en est arrivé là. La fonction debug_backtrace() répond à cette question : elle retourne un instantané de la pile d'appels au point exact où vous l'invoquez, vous permettant de voir quelle fonction a appelé quelle autre, dans quel fichier et à quelle ligne. Cette page explique la signature de la fonction, la structure de l'array qu'elle retourne, des modèles d'utilisation pratiques, et comment elle s'intègre avec les outils de rapport d'erreurs de PHP.

Ce que retourne `debug_backtrace()`

debug_backtrace() retourne un array de tableaux associatifs — un élément par frame de pile, ordonné de l'appel le plus interne (là où vous l'avez invoquée) vers le point d'entrée du script. Elle ne lève jamais d'exception et n'arrête jamais l'exécution ; elle se contente de rapporter la pile courante.

La signature est :

debug_backtrace(int $options = DEBUG_BACKTRACE_PROVIDE_OBJECT, int $limit = 0): array

Paramètres

$options (int) — un masque de bits contrôlant ce que chaque frame inclut :
- DEBUG_BACKTRACE_PROVIDE_OBJECT (par défaut) — inclure l'object réel pour les appels de méthodes.
- DEBUG_BACKTRACE_IGNORE_ARGS — omettre l'index args, ce qui allège la sortie et évite de conserver des références vers des arguments volumineux.
$limit (int) — le nombre maximum de frames à retourner. 0 (par défaut) signifie toute la pile. Utile lorsque vous n'avez besoin que de l'appelant immédiat.

Chaque frame

Chaque frame est un tableau associatif pouvant contenir :

function — le nom de la fonction ou méthode appelée.
line — la ligne depuis laquelle l'appel a été effectué.
file — le fichier depuis lequel l'appel a été effectué.
class — le nom de la classe, pour les appels de méthodes.
object — l'instance de l'object, lorsque DEBUG_BACKTRACE_PROVIDE_OBJECT est défini.
type — -> pour les appels d'instance, :: pour les appels statiques, absent pour les fonctions ordinaires.
args — les arguments passés à l'appel (sauf si DEBUG_BACKTRACE_IGNORE_ARGS est utilisé).

Exemple de base : tracer la pile d'appels

Ce script parcourt trois fonctions imbriquées et affiche une trace lisible depuis la plus profonde :

<?php
function levelThree() {
    $trace = debug_backtrace();
    foreach ($trace as $i => $frame) {
        echo "#$i {$frame['function']}() at line {$frame['line']}\n";
    }
}
function levelTwo() { levelThree(); }
function levelOne() { levelTwo(); }
levelOne();

Sortie :

#0 levelThree() at line 8
#1 levelTwo() at line 9
#2 levelOne() at line 10

La frame #0 correspond à l'endroit où debug_backtrace() a été appelée, et chaque frame suivante est l'appelant au-dessus. Utilisez print_r($trace) à la place de la boucle si vous souhaitez voir toutes les clés (file, args, etc.) en une seule fois.

Identifier l'appelant

Une utilisation courante et ciblée consiste à déterminer qui a appelé la fonction courante — pour la journalisation ou les avertissements de dépréciation. Passez DEBUG_BACKTRACE_IGNORE_ARGS pour alléger le résultat et 2 comme limite, puis lisez l'index de frame 1 (l'index 0 correspond à la fonction courante) :

<?php
function logCaller() {
    $caller = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 2)[1] ?? null;
    if ($caller) {
        echo "Called by {$caller['function']}() on line {$caller['line']}\n";
    }
}
function doWork() {
    logCaller();
}
doWork();

Sortie :

Called by doWork() on line 11

Le guard ?? null est important lorsque logCaller() est invoquée depuis le niveau supérieur, où il n'existe pas de frame 1.

Quand l'utiliser

Journalisation et diagnostics — attachez une trace à une entrée de log pour reconstruire comment un état inattendu a été atteint.
Avis de dépréciation — signalez l'appelant exact d'une fonction que vous êtes en train de supprimer progressivement.
Gestionnaires d'erreurs personnalisés — enrichissez un callback set_error_handler() avec la pile d'appels environnante.
Comprendre le flux d'un framework — voyez quel middleware ou hook a conduit à votre code.

Points d'attention

Performance et mémoire. Avec les options par défaut, chaque frame conserve des références vers args et object, ce qui peut être lourd. Dans les chemins critiques ou lorsque les arguments sont volumineux, passez DEBUG_BACKTRACE_IGNORE_ARGS.
Code en production. Traitez debug_backtrace() comme un outil de débogage. Ne le laissez pas afficher en sortie en production — redirigez-le vers un log à la place.
Besoin uniquement d'un affichage ? Utilisez debug_print_backtrace(), qui affiche directement une trace formatée sans retourner un array.
Dans une exception ? L'object Exception levé porte déjà sa trace via $e->getTrace() et $e->getTraceAsString().

Types d'erreurs PHP en un coup d'œil

debug_backtrace() est plus utile lorsque vous savez qu'une erreur s'est produite et que vous souhaitez obtenir du contexte. Les erreurs PHP se répartissent en quelques grandes catégories :

Erreurs d'analyse (syntaxe) — code invalide que le parseur rejette avant l'exécution, comme un point-virgule manquant ou une accolade non fermée. Ces erreurs sont fatales.
Erreurs logiques — le code s'exécute mais produit un résultat incorrect ; il n'y a aucun message d'erreur, ce qui est précisément le moment où une backtrace est utile.
Erreurs d'exécution — levées pendant l'exécution du script, allant des notices et avertissements non fatals (variable indéfinie, include manquant, avertissements de division) aux erreurs fatales (appel d'une méthode sur un non-object, dépassement de la limite mémoire) qui stoppent l'exécution.

Pour contrôler lesquelles vous voyez, définissez le niveau avec error_reporting(). En développement, activez tout :

<?php
// Report all errors, notices and warnings, and show them
error_reporting(E_ALL);
ini_set('display_errors', '1');

graph TD;
    A[PHP Error] -->|invalid code| B(Parse / Syntax)
    A -->|wrong result| C(Logical)
    A -->|while running| D(Runtime)
    D --> E(Notice / Warning)
    D --> F(Fatal Error)

Sujets connexes

debug_print_backtrace() — afficher une backtrace formatée.
error_reporting() — choisir quelles erreurs sont rapportées.
trigger_error() — lever vos propres erreurs.
PHP Exceptions — gestion structurée des erreurs avec try/catch.

Pratique

Que fait la fonction debug_backtrace() en PHP ?

Elle génère une erreur de syntaxe PHP et arrête le script.Elle produit une backtrace, montrant les appels de fonctions effectués jusqu'au moment où elle a été appelée.Elle retourne un tableau associatif avec la pile d'appels.Elle optimise le code PHP pour de meilleures performances.

Ce que retourne debug_backtrace()