rfc:stack-frame-class

Differences

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

Link to this comparison view

Next revision		Previous revision
rfc:stack-frame-class [2020/07/07 18:38] – created 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'' 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 ==== 
 + 
 +''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> 
 +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 {} 
 +} 
 +</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 =====
-...+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) ===== ===== Proposed PHP Version(s) =====
-Next PHP 8.x+Next PHP 8.0
  
 ===== RFC Impact ===== ===== RFC Impact =====
 ==== To SAPIs ==== ==== To SAPIs ====
-None+None.
  
 ==== To Existing Extensions ==== ==== To Existing Extensions ====
Line 31: Line 94:
  
 ==== New Constants ==== ==== New Constants ====
-Not yet.+None.
  
-===== Future Scope ===== 
-This section details areas where the feature might be improved in future, but that are not currently proposed in this RFC. 
  
 ===== Proposed Voting Choices ===== ===== Proposed Voting Choices =====
-Include these so readers know where you are heading and can discuss the proposed voting options.+As this is a change in exception handling mechanism it requires 2/3 accepted.
  
-===== Patches and Tests ===== +The vote will be a simple Yes/No for ''StackFrame'' inclusion and second vote a simple Yes/No for exception trace replacement.
-Links to any external patches and tests go here.+
  
-If there is no patch, make it clear who will create a patch, or whether a volunteer to help with implementation is needed.+===== Vote ===== 
 +Voting opened 2020-07-21 and closes 2020-08-04.
  
-Make it clear if the patch is intended to be the final patch, or is just a prototype.+<doodle title="Add object-based debug_backtrace() alternative?" auth="brzuchal" voteType="single" closed="true"> 
 +   * Yes 
 +   * No 
 +</doodle>
  
-For changes affecting the core language, you should also provide a patch for the language specification.+'''' 
 + 
 +<doodle title="Replace object-based trace for Throwable::getTrace()?" auth="brzuchal" voteType="single" closed="true"> 
 +   * Yes 
 +   * No 
 +</doodle>
  
 ===== Implementation ===== ===== Implementation =====
-After the project is implemented, this section should contain  +  * [[https://github.com/php/php-src/pull/5820|PR]]
-  - the version(s) it was merged into +
-  - a link to the git commit(s) +
-  - a link to the PHP manual entry for the feature +
-  - a link to the language specification section (if any) +
- +
-===== References ===== +
-Links to external references, discussions or RFCs +
- +
-===== Rejected Features ===== +
-Keep this updated with features that were discussed on the mail lists.+
rfc/stack-frame-class.txt · Last modified: 2020/08/04 08:00 by brzuchal

Page Tools