PHP RFC: StackFrame class

• Version: 1.2
• Date: 2020-07-07
• Author: Michał Marcin Brzuchalski, brzuchal@php.net
• Status: Declined
• Target Version: PHP 8.0
• First Published at: http://wiki.php.net/rfc/stack-frame-class
• Implementation: https://github.com/php/php-src/pull/5820

The debug_backtrace() function currently returns stack trace frames as an array of arrays with information about the file, line, class, type, object, args and function name as keys. This RFC proposes to add a debug_backtrace() alternative which returns an array of objects instead. This reduces memory usage and makes code operating on frames more readable.

Introduce new StackFrame class with static method getTrace() returning array of StackFrame object instances.

There are two places where this could be a replacement for retrieving trace in array of arrays way and these are ReflectionGenerator::getTrace() and Throwable::getTrace(). These should be a subject of the secondary vote.

StackFrame class provides properties which mirrors information from debug_backtrace().

There are additional properties and methods which expose additional information:

• property object_class exposes object class which is useful when $option passed without DEBUG_BACKTRACE_PROVIDE_OBJECT flag;
• property closure exposes a closure within the frame was produced upon.

final class StackFrame implements ArrayAccess
{
    public ?string $file;
 
    public ?int $line;
 
    public ?string $function;
 
    public ?string $class;
 
    public ?object $object;
 
    public ?string $objectClass;
 
    public ?string $type;
 
    public ?\Closure $closure;
 
    public array $args = [];
 
    public static function getTrace(int $options = DEBUG_BACKTRACE_PROVIDE_OBJECT, int $limit = 0): array {}
}

An example below shows exactly the same portion of information as if it would call debug_backtrace() instead of StackFrame::getTrace().

function frames() {
    return StackFrame::getTrace();
}
$frame = frames()[0];
 
var_dump([
    'file' => $frame['file'],
    'line' => $frame['line'],
    'function' => $frame['function'],
    'class' => $frame['class'],
    'type' => $frame['type'],
    'object' => $frame['object'],
    'args' => $frame['args'],
]);

On a test script with 1M recursions to produce huge result results were as above:

1. StackFrame::getTrace() execution time was 0.299s and memory usage was only 192.96MB.
2. debug_backtrace() execution time is 0.333s which is similar but the memory usage was 390.96MB.

If vote decides about changing Exception trace with array of StackTrace objects then Exception::getTrace() method will no longer be a mutable array of arrays with simple keys. Although a StackFrame implements ArrayAccess interface and allow to read all keys in BC manner manipulation on frames will no longer be possible.

Next PHP 8.0

None.

None.

None.

None.

As this is a change in exception handling mechanism it requires 2/3 accepted.

The vote will be a simple Yes/No for StackFrame inclusion and second vote a simple Yes/No for exception trace replacement.

Voting opened 2020-07-21 and closes 2020-08-04.

Add object-based debug_backtrace() alternative?
Real name	Yes	No
alcaeus (alcaeus)
alec (alec)
asgrim (asgrim)
ashnazg (ashnazg)
brzuchal (brzuchal)
bwoebi (bwoebi)
carusogabriel (carusogabriel)
derick (derick)
galvao (galvao)
geekcom (geekcom)
guilhermeblanco (guilhermeblanco)
jasny (jasny)
jhdxr (jhdxr)
kalle (kalle)
marandall (marandall)
nicolasgrekas (nicolasgrekas)
nikic (nikic)
ocramius (ocramius)
pollita (pollita)
ramsey (ramsey)
reywob (reywob)
sebastian (sebastian)
sergey (sergey)
svpernova09 (svpernova09)
tandre (tandre)
twosee (twosee)
wyrihaximus (wyrihaximus)
zimt (zimt)
Final result:	14	14
This poll has been closed.

Replace object-based trace for Throwable::getTrace()?
Real name	Yes	No
alcaeus (alcaeus)
alec (alec)
asgrim (asgrim)
ashnazg (ashnazg)
brzuchal (brzuchal)
bwoebi (bwoebi)
carusogabriel (carusogabriel)
derick (derick)
dragoonis (dragoonis)
galvao (galvao)
guilhermeblanco (guilhermeblanco)
jasny (jasny)
kalle (kalle)
marandall (marandall)
nicolasgrekas (nicolasgrekas)
nikic (nikic)
ocramius (ocramius)
ramsey (ramsey)
sebastian (sebastian)
sergey (sergey)
svpernova09 (svpernova09)
tandre (tandre)
twosee (twosee)
wyrihaximus (wyrihaximus)
zimt (zimt)
Final result:	6	19
This poll has been closed.

• PR