In PHP, debug_backtrace() returns an array that describes the chain of function calls that led to the current line of code. Each item in the array is one step, called a frame.
Think of it as a trail of breadcrumbs. If function first() calls second(), and second() calls third(), then debug_backtrace() called inside third() lists all three. This is very helpful when you want to know who called a function, or when you are hunting for a bug.
Syntax
Call debug_backtrace() with the values you need. Start with this line.
PHP
$trace = debug_backtrace();
Call
What it does
debug_backtrace()
Returns every frame, including the arguments and the object for method calls.
debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS)
Returns the frames without the args key, which uses less memory.
debug_backtrace(0, 2)
Returns only the two most recent frames.
Frame 0 is the function that called debug_backtrace(). The next frame is the caller of that function, and so on. Each frame can contain the keys function, line, file, class, object, type and args.
Library declarations
PHP
debug_backtrace(?int $options = DEBUG_BACKTRACE_PROVIDE_OBJECT, int $limit = 0): array
Parameters
Parameter
Description
options
Optional. A bitmask. DEBUG_BACKTRACE_PROVIDE_OBJECT (the default) adds the object key for method calls. DEBUG_BACKTRACE_IGNORE_ARGS leaves out the args key. Use 0 to skip both.
limit
Optional. The maximum number of frames to return. The default is 0, which means no limit.
Return Value
Return Value
Description
array
A list of frames, with the most recent call first. Each frame is an associative array. The list is empty if there is no function call to report, for example when called at the top level of a script.
PHP Examples
Example 1 — Listing the Call Chain
Three functions call each other. Inside the last one we ask for the backtrace and print the function names.
PHP
<?php
function third() {
$trace = debug_backtrace();
foreach ($trace as $i => $frame) {
echo $i, ": ", $frame['function'], "()", PHP_EOL;
}
}
function second() {
third();
}
function first() {
second();
}
first();
Output
0: third()
1: second()
2: first()
How It Works
first() calls second(), and second() calls third(). That is the call chain.
Inside third(), debug_backtrace() returns one frame for each function call that is still active.
Frame 0 is third() itself, frame 1 is second(), and frame 2 is first().
Every frame is an array, and its function key holds the name of the function.
Example 2 — Hiding Arguments with DEBUG_BACKTRACE_IGNORE_ARGS
By default each frame includes the values that were passed in. You can switch that off with an option flag.
PHP
<?php
function show(int $a, int $b) {
$with = debug_backtrace();
$without = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS);
echo "Default has args: ", isset($with[0]['args']) ? 'yes' : 'no', PHP_EOL;
echo "Ignore args has args: ", isset($without[0]['args']) ? 'yes' : 'no', PHP_EOL;
echo "Number of args: ", count($with[0]['args']), PHP_EOL;
}
show(5, 10);
Output
Default has args: yes
Ignore args has args: no
Number of args: 2
How It Works
show() is called with two numbers, 5 and 10.
The first debug_backtrace() call uses the default options, so frame 0 has an args key.
The second call passes DEBUG_BACKTRACE_IGNORE_ARGS, so the args key is left out.
count() on the args of the first call gives 2, because two values were passed to show().
Example 3 — Limiting the Number of Frames
The second argument is a limit. It is a simple way to keep the result small when the call chain is long.
PHP
<?php
function level3() {
return debug_backtrace(0, 2);
}
function level2() {
return level3();
}
function level1() {
return level2();
}
$trace = level1();
echo "Frames: ", count($trace), PHP_EOL;
foreach ($trace as $frame) {
echo $frame['function'], PHP_EOL;
}
Output
Frames: 2
level3
level2
How It Works
The chain is level1() then level2() then level3(), so there are three active calls.
debug_backtrace(0, 2) uses 0 for the options and 2 for the limit.
Only the two most recent frames are returned, so level1 is cut off.
The loop prints the function name of each remaining frame: level3 and level2.
Frequently Asked Questions
It returns an array that lists the function and method calls that led to the current line. Each item tells you the function name, the line, the file and, optionally, the arguments and object.
debug_backtrace() gives you the data as an array so you can loop over it, filter it, or save it. debug_print_backtrace() prints a readable version straight to the output and returns nothing.
If you call it at the top level of a script, there is no function call to describe, so the array is empty. Call it from inside a function or method to see frames.
Call debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 2) and read frame 1. Frame 0 is the current function, and frame 1 is its caller, so $trace[1]['function'] gives the caller name.
It is fine for debugging, but it does extra work and can use a lot of memory when arguments and objects are included. Use DEBUG_BACKTRACE_IGNORE_ARGS and a limit if you call it often.