rfc:stack-frame-class

Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
rfc:stack-frame-class [2020/07/07 20:07]
brzuchal
rfc:stack-frame-class [2020/08/04 08:00]
brzuchal change status to declined
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   * 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 ===== ===== Introduction =====
Line 11: Line 12:
  
 ===== 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 provides properties and methods which mirrors information from ''debug_backtrace()'':+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 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.
  
 <code php> <code php>
 final class StackFrame implements ArrayAccess final class StackFrame implements ArrayAccess
 { {
-    public readonly string $file;+    public ?string $file;
          
-    public readonly int $line;+    public ?int $line;
          
-    public readonly ?string $function;+    public ?string $function;
          
-    public readonly ?string $class;+    public ?string $class;
          
-    public readonly ?object $object; +    public ?object $object;
-     +
-    public readonly array $args; +
-     +
-    public static function getTrace(): array {}+
  
-    public function getFile(): string {}+    public ?string $objectClass;
  
-    public function getLine(): int {}+    public ?string $type;
  
-    public function getFunction(): ?string {} +    public ?\Closure $closure; 
- +     
-    public function getClass(): ?string {} +    public array $args = []; 
- +     
-    public function getObject(): ?object {}+    public static function getTrace(int $options = DEBUG_BACKTRACE_PROVIDE_OBJECT, int $limit = 0): array {} 
 +
 +</code>
  
-    public function getType(): ?string {}+==== Example ==== 
 +An example below shows exactly the same portion of information as if it would call ''debug_backtrace()'' instead of ''StackFrame::getTrace()''.
  
-    public function getArgs(): array {}+<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> </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 67: 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.txt · Last modified: 2020/08/04 08:00 by brzuchal