PHP 8.0: Stack trace as string - Parameter max length is configurable

Version8.0
TypeNew Feature

Exceptions thrown in PHP can optionally print the exception information on screen, or return a string with the exception, including the stack trace. 

function test() {
    try {
        throw new \Exception();
    }
    catch (Exception $ex) {
        echo $ex;
    }
}

test('1234567890123456789);
Exception in ...:...
Stack trace:
#0 ...(...): test('123456789012345...')

By default, the length of the parameters in the stack trace is truncated to 15 bytes, followed by .... Notice how the line is truncated to 15 bytes, followed by an ellipsis.

test('123456789012345...')

In PHP 7.4, a new INI setting named zend.exception_ignore_args was added, which can completely hide the parameter information from stack trace. 

zend.exception_ignore_args=false

An INI directive like above will completely hide the parameters in stack trace.

In PHP 8.0, there is a new INI directive to limit the length of the parameters shown in stack trace. Note that the zend.exception_ignore_args directive can still completely hide the parameter information from stack traces. 

zend.exception_string_param_max_len=42

This somewhat lengthy but unambiguous directive can expand the stack traces to show more information in the stack trace. They can help ease debugging because a maximum length of 15 bytes is often not enough for URLs (https://www. for example is already 12 bytes, leaving only three bytes for the remaining of it), database queries, etc.

To prevent a misconfigured configuration from writing or outputting too much data due this change, there is a hard limit of 1000000 bytes to this directive.

Note that this change only affects when a Throwable (see hierarchy of PHP exceptions) is coerced to a string, explicitly retrieved as a string, or when an uncaught exception is printed on screen.

  1. When a \Throwable is coerced to string, such as (string) $exception or echo $exception.
  2. When a \Throwable is retrieved as string, with $exception->getTraceAsString(), i.e. Throwable::getTraceAsString().
  3. Default errors printed on screen when an exception is uncaught.

This change does not affect debug_print_backtrace function or Throwable::getTrace method, as they both return the full stack trace.

Backwards Compatibility Impact

The default configuration value of zend.exception_string_param_max_len remains 15 bytes. This means unless this value is not updated, the stack traces would be the same.

Related Changes

RFC Discussion Implementation