PHP: rfc:display_error_function_args

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== 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

===== Introduction =====

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>
<?php

unlink("/tmp");
chown("/", "calvin");
chmod("/", 0777);
</PHP>

Currently, you get the following output:

<code>
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
</code>

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

<code>
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
</code>

===== Proposal =====

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:

<code>
% 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
</code>

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|Error Backtraces v2]]" RFC chose to not do so.

===== Backward Incompatible Changes =====

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.)

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

Next PHP minor release.

===== RFC Impact =====

==== To the Ecosystem ====

None.

==== To Existing Extensions ====

None.

==== To SAPIs ====

None.

===== Open Issues =====

===== Future Scope =====

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

===== Voting Choices =====

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

<doodle title="Add a display_error_function_args INI setting as described" voteType="single" closed="true" closeon="2026-01-01T15:30:00Z">
   * Yes
   * No
   * Abstain
</doodle>

----

This vote requires a simple majority:

<doodle title="Default value for display_error_function_args" voteType="single" closed="true" closeon="2026-01-01T15:30:00Z">
   * "1"
   * "0" 
   * Abstain
</doodle>

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:

<doodle title="If display_error_function_args defaults to 1, default value in run-tests.php" voteType="single" closed="true" closeon="2026-01-01T15:30:00Z">
   * "1"
   * "0" 
   * Abstain
</doodle>

===== Patches and Tests =====

[[https://github.com/php/php-src/pull/12276|Implementation PR]]

===== Implementation =====

Not merged yet.

===== References =====

[[https://externals.io/message/130249|Internals discussion]]

===== Rejected Features =====

===== Changelog =====
Page Tools
