# RFC: Error backtraces

- Status: Obsolete
- Authors: Max Semenik, maxsem.wiki@gmail.com
- Date: 2020-05-25
- Version: 1.0
- Original: https://wiki.php.net/rfc/error_backtraces
- Page: https://externals.io/rfc/error_backtraces
- More for agents: search with https://externals.io/search.md?q={query} · RFCs at https://externals.io/rfc.md · JSON API at https://externals.io/api · documentation at https://externals.io/llms.txt

## Discussions on the mailing list

- [RFC: Error backtraces](https://externals.io/message/110302.md) — started on 2020-05-29, 7 messages
- [\[RFC\] \[Discussion\] Error backtraces v2](https://externals.io/message/126110.md) — started on 2024-12-05, 13 messages

---

> This proposal has been **superseded** by [Error Backtraces v2](https://externals.io/rfc/error_backtraces_v2), which has been implemented in PHP 8.5.

## 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 [an extension](https://github.com/wikimedia/php-wmerrors) 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.:

```
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}
```

**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:

```
#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}"
}
```

**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 [avoid outputting backtraces for unhandled exceptions twice](https://github.com/php/php-src/pull/5642/files#diff-1a9cfc6173e3a434387996e46086da56R1310), 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.