debug_print_backtrace()

Introduction

When a PHP script reaches an error, knowing where it is isn't always enough — you also need to know how it got there: which function called which, in what order. That chain of calls is the call stack, and debug_print_backtrace() prints it for you, ready-formatted, right to the output. It's the fastest way to answer "what path led to this line?" without setting up a full debugger like Xdebug.

This chapter covers what the function does, its parameters, how to read its output, when to reach for it, and how it differs from its sibling debug_backtrace().

What debug_print_backtrace() Does

debug_print_backtrace() walks the current call stack — every active function or method call from the top-level script down to the spot where you called it — and prints a human-readable trace. Unlike debug_backtrace(), which returns the stack as an array for you to inspect or log, debug_print_backtrace() writes the formatted text directly to the standard output and returns nothing (void).

Use it when you just want to see the call path immediately. Use debug_backtrace() when you need to process the stack (filter frames, store it, send it to a logger).

Syntax

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

Both parameters are optional:

• $options — a bitmask that tweaks the output. The only flag is DEBUG_BACKTRACE_IGNORE_ARGS, which omits the ["params"] (function arguments) from each frame. Passing 0 (the default) includes argument summaries.
• $limit — caps the number of stack frames printed. 0 (the default) means no limit. Useful in deep recursion when you only care about the few most recent calls. Available since PHP 5.4.0.

Basic Usage

Call the function from anywhere in your script. Consider three functions that call one another in sequence:

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

function b()
{
    c();
}

function c()
{
    debug_print_backtrace();
}

a();
?>

Here a() calls b(), which calls c(), which calls debug_print_backtrace(). The output is a numbered list, most recent call first:

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

Read it top to bottom as "innermost to outermost": frame #0 is where c() ran (line 9), #1 is its caller b() (line 4), and #2 is the original call site a() (line 17). Each line shows the file, the line number in parentheses, and the function that was running. The script entry point itself isn't listed as a frame because it has no caller.

Limiting the Number of Frames

In recursive or deeply nested code the trace can be long. Pass a $limit to keep only the nearest frames:

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

countdown(5);
?>

Only two frames are printed even though countdown() recursed several times:

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

Hiding Arguments

By default each frame shows a summary of the arguments passed (as seen above with countdown(2)). For sensitive data — passwords, tokens — or simply to reduce noise, pass DEBUG_BACKTRACE_IGNORE_ARGS:

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

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

The frame still appears, but the password no longer leaks into the trace:

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

When to Use It

• Tracing unexpected calls — a method runs when you didn't expect it to; drop a backtrace at the top to see who triggered it.
• Understanding legacy code — quickly map the call flow without stepping through a debugger.
• Logging context on errors — though for logging, prefer debug_backtrace() so you can capture the stack as a string and route it to a file (see the note below).

Gotchas

• It prints, it doesn't return. You can't assign its result to a variable. If you need the stack for logging, use debug_backtrace() instead.
• Output goes to the response. In a web request the trace lands in the page output (or browser), which can corrupt HTML or JSON. Strip these calls before shipping to production — or use a logging-friendly alternative.
• Capturing it as a string. If you do want debug_print_backtrace()'s formatting in a log, wrap it in output buffering:

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

Related Functions

• debug_backtrace() — returns the call stack as an array instead of printing it.
• var_dump() and print_r() — inspect the values of variables while debugging.
• error_reporting() — control which errors PHP surfaces in the first place.

Conclusion

debug_print_backtrace() is a one-line way to print the chain of function calls that led to the current point in a PHP script. Its optional $options and $limit parameters let you hide arguments and trim long traces. Remember that it prints rather than returns — for programmatic access to the stack, reach for debug_backtrace(), and remove print-based traces before deploying to production.

Practice