rfc:stack-frame-class

This is an old revision of the document!


PHP RFC: StackFrame class

Introduction

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.

Proposal

Introduce new StackFrame with static method getTrace().

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

StackFrame class provides properties and methods which mirrors information from debug_backtrace():

final class StackFrame implements ArrayAccess
{
    public readonly string $file;
 
    public readonly int $line;
 
    public readonly ?string $function;
 
    public readonly ?string $class;
 
    public readonly ?object $object;
 
    public readonly array $args;
 
    public static function getTrace(): array {}
 
    public function getFile(): string {}
 
    public function getLine(): int {}
 
    public function getFunction(): ?string {}
 
    public function getClass(): ?string {}
 
    public function getObject(): ?object {}
 
    public function getType(): ?string {}
 
    public function getArgs(): array {}
}

Performance

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.

Backward Incompatible Changes

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.

Proposed PHP Version(s)

Next PHP 8.0

RFC Impact

To SAPIs

None.

To Existing Extensions

None.

To Opcache

None.

New Constants

None.

Proposed Voting Choices

As this is a language 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.

Implementation

rfc/stack-frame-class.1594154245.txt.gz · Last modified: 2020/07/07 20:37 by brzuchal