Table of Contents

PHP RFC: Change default zend.exception_ignore_args INI setting

Introduction

The zend.exception_ignore_args INI setting was introduced in PHP 7.4.0 and allows arguments to be excluded from stack traces generated for exceptions.

When the INI setting was introduced the value suggested for Production environments was On, meaning that arguments are excluded. However this is only a suggestion and both the default value, and the developer-suggested value, were left at Off, meaning that all arguments in the stack trace are included.

The intention of this change is to make the language safer by default and reduce the risk of unintended information disclosure. This is achieved by changing the default value of the setting to be On, thereby removing arguments from typical stack traces.

The value of this INI setting impacts the way that exceptions are displayed in several locations, including:

Note: Some backtrace handling methods are not subject to the zend.exception_ignore_args INI setting, and instead accept a flag to determine whether to ignore the args. These methods are:

In these cases the arguments can be excluded from the backtrace by passing the DEBUG_BACKTRACE_IGNORE_ARGS flag to the $options parameter.

Proposal

Change the default value of the INI setting to On, meaning that arguments are excluded from stack traces by default.

I believe these changes are both pragmatic and considerate of the wide range of skill levels among PHP users.

Why existing features are insufficient

Changing the ''display_errors'' INI setting

One alternative to this proposal is to disable the display of errors. The default for the display_errors INI setting could instead be modified to be Off thereby further reducing impact. However displaying errors is often helpful when debugging an application; and the logs can still be helpful, and relatively safe, without including the stacktrace arguments. Ideally both INI settings should be updated and not one, or the other.

Proper configuration of a framework's error handler

Ideally, all frameworks and applications should always be correctly configured. However, mistakes happen, and PHP should provide the safest and most pragmatic default configuration, regardless of framework.

Frameworks are already able to modify the INI setting using ini_set() if they do require these arguments, and documentatino can guide users to update their configuration if required.

#[\SensitiveParameter]

A new #[\SensitiveParameter] was introduced in PHP 8.2.0 to mask parameters in stack traces, however it has some shortcomings which make it unsuitable in many cases — notably where parameters are passed to external libraries not under your own control.

The main issue with this parameter is that it only masks the parameter at the point that it is defined. A sensitive parameter does not automatically apply at any point higher or lower in the stack trace, potentially revealing sensitive information unless the entire codebase is audited for potential issues. For example: 

<?php
 
class Example {
    public function doSomething(
        #[\SensitiveParameter] $sensitive,
    ): void {
        $this->doSomethingElse($sensitive);
    }
 
    public function doSomethingElse(
        $sensitive,
    ): void {
        throw new \Exception('Something went wrong');
    }
}
 
$example = new Example();
try {
    $example->doSomething('MySecretValue');
} catch (\Exception $e) {
    print_r($e->getTraceAsString());
}
 
/*
# 0 /in/ve6SG(7): Example->doSomethingElse('MySecretValue')
# 1 /in/ve6SG(19): Example->doSomething(Object(SensitiveParameterValue))
# 2 {main}
*/

Backward Incompatible Changes

No backwards incompatible changes are expected. Any system using the stacktrace arguments must already be capable of handling both the On, and Off INI values already.

Proposed PHP Version(s)

Next minor version, i.e. PHP 8.5.0.

RFC Impact

php.ini Defaults

This RFC proposes changing:

No change is proposed for php.ini-production.

To SAPIs

None.

To Existing Extensions

None.

To Opcache

None.

New Constants

None.

Unaffected PHP Functionality

The behaviour of the following related methods will not change:

Future Scope

This proposal does not alter debug_backtrace() or debug_print_backtrace(), as they already support the DEBUG_BACKTRACE_IGNORE_ARGS flag. However, introducing an explicit DEBUG_BACKTRACE_INCLUDE_ARGS constant could provide greater flexibility for developers who need argument inclusion in stack traces.

If this constant were created then it would also be possible for these methods to respect the zend.exception_ignore_args INI setting as their default state.

Another future consideration may be to extend the same flag usage to the Throwable::getTrace() and Throwable::getTraceAsString() methods to improve consistency.

Proposed Voting Choices

(Each child vote result will be considered only if its parent vote passes.)

(The voting period would be two weeks)

Patches and Tests

A patch has been created to implement the first part of this change. Changing the php.ini-development file is a small additional change that can be added.

Implementation

After the project is implemented, this section should contain

References

Rejected Features