PHP RFC: Display Function Arguments in Errors

• Version: 0.9
• Date: 2026-03-09
• Author: Calvin Buckley, calvinb@php.net
• Status: Draft
• Implementation: https://github.com/php/php-src/pull/12276

PHP errors (and warnings, notices, etc.) show the function that raised them. However, the display of parameters in these errors is inconsistent. In practice, only basic stream functions provide parameters, and it isn't derived from the parameters that the function was called with.

For example, take this very simple script:

<?php
 
unlink("/tmp");
chown("/", "calvin");
chmod("/", 0777);

Currently, you get the following output:

Warning: unlink(/tmp): Operation not permitted in /Users/calvin/src/chmod.php on line 3

Warning: chown(): Operation not permitted in /Users/calvin/src/chmod.php on line 4

Warning: chmod(): Operation not permitted in /Users/calvin/src/chmod.php on line 5

(For internals people, this is because the unlink stream function calls php_error_docref1, which provides text in between the parenthesis. There is also php_error_docref2, but this is called even less. There are no docref functions that take more; 99.9% of code calls php_error_docref, which itself has a somewhat vestigial docref parameter that links to the documentation.)

In an error log, if you see this, you may know what function failed, but without knowing what file it say, tried to change ownership on, you may have to look at the source for the why. In a simple script, that may not be a problem if the values are hardcoded or immediately obvious from context. In larger applications that tend to have more complex functions that wrap existing PHP functions, you may have to do more involved debugging.

What this RFC proposes is including the parameters that were actually passed to that function, when that function raises an error. This makes it easier to see at a glance what may have failed, and help narrow down debugging. Unlike php_error_docref1 (and 2), this doesn't expect internals to know what parameters a user may want to know. For example, the output of the above script, if this proposed is passed:

Warning: unlink('/tmp'): Operation not permitted in /Users/calvin/src/chmod.php on line 3

Warning: chown('/', 'calvin'): Operation not permitted in /Users/calvin/src/chmod.php on line 4

Warning: chmod('/', 511): Operation not permitted in /Users/calvin/src/chmod.php on line 5

Add a display_error_function_args, which potentially defaults to “1”. This is made an INI option, as some users may want to turn it off (i.e. risks of untagged PII in logs, size of logs, format compatibility with older versions of PHP).

When enabled, PHP will include function parameters in errors raised by functions. This uses the same infrastructure as backtraces for exceptions and fatal errors, so existing behaviours are borrowed. For example, the zend.exception_string_param_max_len INI option is respected (so it won't fill up logs with huge strings), as is the SensitiveParameter attribute (so it won't leak passwords and such with i.e. mysqli_connect or password_hash). In the event that a string containing the arguments couldn't be built (for example, if the system is out of memory), then it will fall back to showing the parameters set by php_error_docref1 (and 2). For example:

% sapi/cli/php -d zend.exception_string_param_max_len=2 -d display_error_function_args=1 ../chmod.php
[...]
Warning: odbc_connect('BO...', 'us...', Object(SensitiveParameterValue)): SQL error: [unixODBC][Driver Manager]Data source name not found and no default driver specified, SQL state IM002 in SQLConnect in /Users/calvin/src/chmod.php on line 7

Even if we do enable this by default, we may not want to do so for tests. Because of the wide impact to the formatting of tests, this would involve touching a large majority of PHP tests (there are currently over 21000 today). While my implementation PR does attempt to update bless.php for common cases where strings can now be visible and need to be adjusted for (i.e. paths including usernames), bless can still munge the expect sections in a way that requires manual adjustment. There is precedent for not using this; the “Error Backtraces v2” RFC chose to not do so.

If the sub-vote to change the default to “1” passes, the format of docref error output changes, and will likely not match the format existing code expects. (There will be a subvote to change the defaults for tests.)

Next PHP minor release.

None.

None.

None.

• The php_error_docref1 and php_error_docref2 functions could be deprecated and removed, as there are few callers, and having this RFC be implemented in practice would obsolete it in almost every case except i.e. out of memory situations.
• An attribute to affect formatting of parameters in error/backtrace printing would be desirable, i.e. for the chmod flags to be printed as octal.

Primary Vote requiring a 2/3 majority to accept the RFC:

This vote requires a simple majority:

This vote requires a simple majority, and determines if we should enable display_error_function_args for tests, and to update all tests in the php-src repository that feature errors with function parameters:

Implementation PR

Not merged yet.

Internals discussion