rfc:stack-frame-class

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
rfc:stack-frame-class [2020/07/07 19:42] – brzuchalrfc:stack-frame-class [2020/08/04 08:00] (current) – change status to declined brzuchal
Line 1: Line 1:
 ====== PHP RFC: StackFrame class ====== ====== PHP RFC: StackFrame class ======
-  * Version: 0.9+  * Version: 1.2
   * Date: 2020-07-07   * Date: 2020-07-07
-  * Author: Michał Brzuchalski, <brzuchal@php.net> +  * Author: Michał Marcin Brzuchalski, <brzuchal@php.net> 
-  * Status: Under Discussion+  * Status: Declined 
 +  * Target Version: PHP 8.0
   * First Published at: http://wiki.php.net/rfc/stack-frame-class   * First Published at: http://wiki.php.net/rfc/stack-frame-class
 +  * Implementation: https://github.com/php/php-src/pull/5820
  
 +===== 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. 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.
- 
-===== Introduction ===== 
-... 
  
 ===== Proposal ===== ===== Proposal =====
-Introduce new ''StackFrame'' with static method ''getTrace()'' and optionally replace ''Exception'' class trace with  +Introduce new ''StackFrame'' class with static method ''getTrace()'' returning array of ''StackFrame'' object instances.
-array of ''StackFrame'' objects.+
  
-''StackFrame'' class synopsis:+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.
  
-<code php> +==== StackFrame class ====
-final class StackFrame +
-{ +
-    public static function getTrace(): array {}+
  
-    public function getFile(): string {}+''StackFrame'' class provides properties which mirrors information from ''debug_backtrace()''.
  
-    public function getLine(): int {}+There are additional properties and methods which expose additional information:
  
-    public function getFunction(): ?string {}+  * 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.
  
-    public function getClass(): ?string {}+<code php> 
 +final class StackFrame implements ArrayAccess 
 +{ 
 +    public ?string $file; 
 +     
 +    public ?int $line; 
 +     
 +    public ?string $function; 
 +     
 +    public ?string $class; 
 +     
 +    public ?object $object;
  
-    public function getObject(): ?object {}+    public ?string $objectClass;
  
-    public function getType(): ?string {}+    public ?string $type;
  
-    public function getArgs(): array {}+    public ?\Closure $closure; 
 +     
 +    public array $args = []; 
 +     
 +    public static function getTrace(int $options = DEBUG_BACKTRACE_PROVIDE_OBJECT, int $limit = 0): array {}
 } }
 </code> </code>
 +
 +==== Example ====
 +An example below shows exactly the same portion of information as if it would call ''debug_backtrace()'' instead of ''StackFrame::getTrace()''.
 +
 +<code php>
 +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'],
 +]);
 +</code>
 +
 +==== Performance ====
 +On a test script with 1M recursions to produce huge result results were as above:
 +
 +  - ''StackFrame::getTrace()'' execution time was 0.299s and memory usage was only **192.96MB**.
 +  - ''debug_backtrace()'' execution time is 0.333s which is similar but the memory usage was **390.96MB**.
  
 ===== Backward Incompatible Changes ===== ===== Backward Incompatible Changes =====
Line 56: Line 94:
  
 ==== New Constants ==== ==== New Constants ====
-Not yet.+None.
  
  
 ===== Proposed Voting Choices ===== ===== Proposed Voting Choices =====
-As this is a language in exception handling mechanism it requires 2/3 accepted.+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. The vote will be a simple Yes/No for ''StackFrame'' inclusion and second vote a simple Yes/No for exception trace replacement.
 +
 +===== Vote =====
 +Voting opened 2020-07-21 and closes 2020-08-04.
 +
 +<doodle title="Add object-based debug_backtrace() alternative?" auth="brzuchal" voteType="single" closed="true">
 +   * Yes
 +   * No
 +</doodle>
 +
 +''''
 +
 +<doodle title="Replace object-based trace for Throwable::getTrace()?" auth="brzuchal" voteType="single" closed="true">
 +   * Yes
 +   * No
 +</doodle>
  
 ===== Implementation ===== ===== Implementation =====
-...+  * [[https://github.com/php/php-src/pull/5820|PR]]
rfc/stack-frame-class.1594150964.txt.gz · Last modified: 2020/07/07 19:42 by brzuchal

Page Tools