PHP getTrace() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Exception

Definition

In PHP, Exception::getTrace() returns the stack trace as an array of frames. Each frame can include the file, line, function, class, and arguments from the call chain that led to the exception.

Use getTrace() when you need structured debug data, for example to log JSON or inspect a specific caller. For a ready-made printable string, prefer getTraceAsString(). The method is final.

Syntax

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

PHP
$frames = $e->getTrace();
CallWhat it does
$e->getTrace()Returns the stack trace as an array of frames.
$e->getTrace()[0]["function"] ?? ""Reads the function name from the top frame when present.
count($e->getTrace())Counts how many frames are in the trace.

getTrace() is final. Frame keys commonly include file, line, function, class, type, and args. Argument values may be omitted or limited for safety depending on PHP settings.

Library declarations
PHP
final public Exception::getTrace(): array

Parameters

ParameterDescription
—This method takes no parameters.

Return Value

Return ValueDescription
arrayA list of associative arrays describing call frames from the throw site upward.

PHP Examples

Example 1 — Count Trace Frames

Throw from a nested call and print how many frames getTrace() contains.

PHP
<?php
function levelTwo(): never
{
    throw new Exception("Trace demo");
}

function levelOne(): never
{
    levelTwo();
}

try {
    levelOne();
} catch (Exception $e) {
    echo "Frames: ", count($e->getTrace()), PHP_EOL;
    echo $e->getMessage(), PHP_EOL;
}

How It Works

  1. levelOne() calls levelTwo(), which throws.
  2. getTrace() builds frames for the call chain.
  3. count() shows how many frames were recorded.
  4. The exact count can vary slightly with how PHP records the top frame.

Example 2 — Read Function Names from Frames

Loop over getTrace() and print each function name.

PHP
<?php
function worker(): never
{
    throw new Exception("Worker failed");
}

function runner(): never
{
    worker();
}

try {
    runner();
} catch (Exception $e) {
    foreach ($e->getTrace() as $i => $frame) {
        $fn = $frame["function"] ?? "(unknown)";
        echo "#", $i, " ", $fn, PHP_EOL;
    }
}

How It Works

  1. Each frame is an associative array.
  2. The function key holds the function that was active in that frame.
  3. Index 0 is closest to the throw.
  4. Missing keys are possible, so the example uses ?? for safety.

Example 3 — Prefer String Form for Quick Logs

Compare getTrace() with getTraceAsString() when you only need a quick printable stack.

PHP
<?php
function boom(): never
{
    throw new Exception("Boom");
}

try {
    boom();
} catch (Exception $e) {
    echo "Array frames: ", count($e->getTrace()), PHP_EOL;
    echo substr($e->getTraceAsString(), 0, 12), "...", PHP_EOL;
}

How It Works

  1. getTrace() is best when you need structured fields.
  2. getTraceAsString() is best for plain-text logs.
  3. substr() shows only the beginning of the string form.
  4. Pick the form that matches how you store errors.

Frequently Asked Questions

An array of stack frames describing the call chain that led to the exception.
Use getTrace() when you need to inspect fields in code. Use getTraceAsString() when you want a ready-made multiline string for logs.
No. It is final.
Not always. Frames may omit args, and sensitive values should not be printed publicly even when present.
It records the call stack at the moment the exception was created, not the catch handler’s local variables.

Next: getTraceAsString()

Exception::getTraceAsString() returns the stack trace as a single readable string. Each fr.

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