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();
Call
What 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
Parameter
Description
—
This method takes no parameters.
Return Value
Return Value
Description
array
A 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;
}
Output
Frames: 2
Trace demo
How It Works
levelOne() calls levelTwo(), which throws.
getTrace() builds frames for the call chain.
count() shows how many frames were recorded.
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;
}
}
Output
#0 worker
#1 runner
How It Works
Each frame is an associative array.
The function key holds the function that was active in that frame.
Index 0 is closest to the throw.
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;
}
Output
Array frames: 1
#0 boom()...
How It Works
getTrace() is best when you need structured fields.
getTraceAsString() is best for plain-text logs.
substr() shows only the beginning of the string form.
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.