PHP debug_print_backtrace() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Error

Definition

In PHP, debug_print_backtrace() prints the list of function calls that led to the current line, one call per line. It sends the text straight to the output.

It does the same job as debug_backtrace(), but instead of giving you an array it prints a ready-to-read report. It is a quick way to answer the question: how did my code get here? Because it prints, it returns nothing.

Syntax

Call debug_print_backtrace() with the values you need. Start with this line.

PHP
debug_print_backtrace();
CallWhat it does
debug_print_backtrace()Prints every active call, including the arguments.
debug_print_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS)Prints the calls without showing argument values.
debug_print_backtrace(0, 1)Prints only the most recent call.

The printed lines contain file paths and line numbers, so they look different on every computer. To capture the text instead of showing it, wrap the call in ob_start() and ob_get_clean().

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

Parameters

ParameterDescription
optionsOptional. A bitmask. Use DEBUG_BACKTRACE_IGNORE_ARGS to leave out the argument values. The default is 0, which prints the arguments.
limitOptional. The maximum number of calls to print. The default is 0, which means no limit.

Return Value

Return ValueDescription
voidNothing is returned. The backtrace is printed to the output instead.

PHP Examples

Example 1 — Capturing the Printed Backtrace

The real text contains file paths, so this example captures it with output buffering and then describes it.

PHP
<?php
function third() {
    ob_start();
    debug_print_backtrace();
    return ob_get_clean();
}

function second() {
    return third();
}

function first() {
    return second();
}

$text = first();
$lines = explode("\n", trim($text));

echo "Frames printed: ", count($lines), PHP_EOL;
echo "First line starts with: ", substr($lines[0], 0, 2), PHP_EOL;

How It Works

  1. ob_start() begins collecting everything that is printed instead of showing it.
  2. debug_print_backtrace() prints one numbered line for each active call: third, second and first.
  3. ob_get_clean() hands back the collected text as a string and stops buffering.
  4. Splitting the text on new lines gives 3 lines, and the first line begins with #0.

Example 2 — Limiting the Output

The second argument limits how many calls are printed. Here only the most recent call is shown.

PHP
<?php
function inner() {
    ob_start();
    debug_print_backtrace(0, 1);
    return ob_get_clean();
}

function outer() {
    return inner();
}

$text = outer();
$lines = explode("\n", trim($text));

echo "Lines printed: ", count($lines), PHP_EOL;

How It Works

  1. outer() calls inner(), so there are two active calls.
  2. debug_print_backtrace(0, 1) uses 0 for the options and 1 for the limit.
  3. Only the most recent call, inner(), is printed.
  4. That is why the captured text has just one line.

Example 3 — Hiding Arguments

Normally the argument values appear in the printed line. DEBUG_BACKTRACE_IGNORE_ARGS removes them.

PHP
<?php
function showWithArgs(string $word) {
    ob_start();
    debug_print_backtrace();
    return ob_get_clean();
}

function showWithoutArgs(string $word) {
    ob_start();
    debug_print_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS);
    return ob_get_clean();
}

$a = showWithArgs('secret-value');
$b = showWithoutArgs('secret-value');

echo "Default shows the value: ", str_contains($a, 'secret-value') ? 'yes' : 'no', PHP_EOL;
echo "IGNORE_ARGS shows the value: ", str_contains($b, 'secret-value') ? 'yes' : 'no', PHP_EOL;

How It Works

  1. Both functions receive the same string, secret-value.
  2. showWithArgs() prints the backtrace with default options, so the string is part of the printed line.
  3. showWithoutArgs() passes DEBUG_BACKTRACE_IGNORE_ARGS, so no argument values are printed.
  4. str_contains() checks each captured text, and only the first one contains the word.

Frequently Asked Questions

It prints the list of function calls that led to the current line. Each call gets its own numbered line, starting with #0 for the most recent call.
No. It returns void and prints directly. If you need the text as a string, wrap the call in ob_start() and ob_get_clean(). If you need structured data, use debug_backtrace() instead.
Pass DEBUG_BACKTRACE_IGNORE_ARGS as the first argument. The calls are still listed, but the values that were passed in are left out.
Each line includes the full path of your file and the line number, and the exact layout has changed slightly between PHP versions. The idea is always the same: one line per active call.
No. It is a debugging helper and it can show private data. Remove it before publishing, or send backtraces to a log file with error_log() instead of printing them to visitors.

Next: error_clear_last()

error_clear_last() erases the record of the most recent error, so that error_get_last() re.

error_clear_last() 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