PHP debug_backtrace() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Error

Definition

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

ParameterDescription
optionsOptional. 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.
limitOptional. The maximum number of frames to return. The default is 0, which means no limit.

Return Value

Return ValueDescription
arrayA 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();

How It Works

  1. first() calls second(), and second() calls third(). That is the call chain.
  2. Inside third(), debug_backtrace() returns one frame for each function call that is still active.
  3. Frame 0 is third() itself, frame 1 is second(), and frame 2 is first().
  4. 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);

How It Works

  1. show() is called with two numbers, 5 and 10.
  2. The first debug_backtrace() call uses the default options, so frame 0 has an args key.
  3. The second call passes DEBUG_BACKTRACE_IGNORE_ARGS, so the args key is left out.
  4. 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;
}

How It Works

  1. The chain is level1() then level2() then level3(), so there are three active calls.
  2. debug_backtrace(0, 2) uses 0 for the options and 2 for the limit.
  3. Only the two most recent frames are returned, so level1 is cut off.
  4. 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.

Next: debug_print_backtrace()

debug_print_backtrace() prints the list of function calls that led to the current line, on.

debug_print_backtrace() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

8 people found this page helpful