====== PHP RFC: Error backtraces ======
  * Version: 1.0
  * Date: 2020-05-25
  * Author: Max Semenik, maxsem.wiki@gmail.com
  * Status: Inactive
  * First Published at: https://wiki.php.net/rfc/error_backtraces

===== Introduction =====
PHP errors, unlike exceptions, are much more limited in programmers' ability to control their handling and get detailed information about them. I propose to fix some of these issues by recording a backtrace for every error.

This problem is so serious that, for example, Wikimedia has created [[https://github.com/wikimedia/php-wmerrors|an extension]] for this.

===== Proposal =====
Add backtraces to error output.

**Error output**: traces will be formatted exactly like for exceptions, and appended to error messages, e.g.:
<code>
Fatal error: Allowed memory size of 134217728 bytes exhausted in /var/www/test.php on line 123
#0 /var/www/test.php(123): spl_eat_all_memory()
#1 /var/www/foo.php(456): foo(123, 'foo')
#2 /var/www/bar.php(789): bar()
#3 {main}
</code>

**Logging**: backtraces will be logged just like for exceptions.

**''error_get_last()''** output will have another element added to it if a trace is available:
<code>
#1 {main}
array(5) {
  ["type"]=>
  int(1)
  ["message"]=>
  string(22) "Error, terrible error!"
  ["file"]=>
  string(17) "/var/www/test.php"
  ["line"]=>
  int(3)
  ["backtrace"]=>
  string(123) "#0 /var/www/test.php(345): $this->causeTerribleError()
#1 {main}"
}
</code>

**Configuration**: while always having backtraces is nice for debugging, some people might not like the performance overhead of generating backtraces or the risk of having to generate a trace after a fatal error. I therefore propose to address this with an INI setting, ''debug_backtraces'' that allows to turn this feature on and off, as well as to limit the number of stack frames outputted:
  * 0 - no backtraces
  * positive number - output this number of frames
  * negative value - no limit
By default it would be on in development settings but off in production.

===== Backward Incompatible Changes =====
  * In the current proposed implementation, a new error flag ''E_UNHANDLED_EXCEPTION'' is introduced to [[https://github.com/php/php-src/pull/5642/files#diff-1a9cfc6173e3a434387996e46086da56R1310|avoid outputting backtraces for unhandled exceptions twice]], though it's not included in ''E_ALL'' and is invisible for userspace.
  * From the userspace POV, everything will behave exactly as before with backtraces disabled, while turning them on would introduce a few minor changes to how errors are represented.

===== Proposed PHP Version(s) =====
8.0

===== php.ini Defaults =====
For ''error_backtraces'':
  * Default value: 0
  * php.ini-development value: 100
  * php.ini-production value: 0

===== Open Issues =====
Make sure there are no open issues when the vote starts!

===== Unaffected PHP Functionality =====
Everything other than the minor stuff mentioned in //Backward Incompatible Changes//.

===== Future Scope =====
Backtrace handling code could use some unification and refactoring, but that doesn't require a RFC and thus can be addressed later.

===== Proposed Voting Choices =====
  * Accept this RFC (yes/no)?

===== Patches and Tests =====
  * WIP patch: https://github.com/php/php-src/pull/5642

===== References =====
Links to external references, discussions or RFCs

===== Rejected Features =====
Keep this updated with features that were discussed on the mail lists.