[PHP-DEV] [RFC] Exempt input type and value validation from BC Break policy

Hello internals,

I would like to propose a short policy RFC to formally exempt input type and value validation from our BC Break policy.
The current wording of the policy already permits us to add validation of inputs, but recently any such changes have been asked to submit an RFC instead.
We believe that requiring an RFC for this type of change is detrimental and adds unnecessary friction for routine maintenance activity and new contributors.

RFC: PHP: rfc:policy-exempt-type-value-error-bc-policy

Best regards,

Gina P. Banyard

Am 02.03.2026 um 14:13 schrieb Gina P. Banyard <internals@gpb.moe>:

I would like to propose a short policy RFC to formally exempt input type and value validation from our BC Break policy.
The current wording of the policy already permits us to add validation of inputs, but recently any such changes have been asked to submit an RFC instead.
We believe that requiring an RFC for this type of change is detrimental and adds unnecessary friction for routine maintenance activity and new contributors.

RFC: PHP: rfc:policy-exempt-type-value-error-bc-policy

Playing my favourite broken record:
Can we please state that additions of Exceptions should (in most cases) go through an E_WARNING phase to allow a time window to fix code before changing the behaviour?

I'm fine with not needing an RFC for such changes as long as the migration process is being respected.

Regards,
- Chris

Hi

On 3/2/26 14:49, Christian Schneider wrote:

Playing my favourite broken record:
Can we please state that additions of Exceptions should (in most cases) go through an E_WARNING phase to allow a time window to fix code before changing the behaviour?

“Not passing invalid values” is perfectly backwards compatible. Folks can just fix their code before upgrading their production deployment to the new PHP version, e.g. by trying out the new PHP version in a staging system or running CI for both the old and new PHP version.

In practice an E_WARNING is no less breaking than going straight to an Error, because:

1.

The common frameworks include error handlers that just convert any warning and notice to an Exception.

2.

The code is already broken, because it relies on unspecified behavior. The error would just making the user aware that the code is very likely not doing what it appears to be doing based on the input values passed to a function.

To give a concrete example: The `sort()` function has a second parameter `int $flags = SORT_REGULAR`. So clearly I can pass one of the `SORT_*` constants to it. Let's see which ones we have:

     foreach (get_defined_constants() as $constant => $value) {
         if (str_starts_with($constant, 'SORT_')) {
             echo $constant, ": ", $value, PHP_EOL;
         }
     }

This prints:

     SORT_ASC: 4
     SORT_DESC: 3
     SORT_REGULAR: 0
     SORT_NUMERIC: 1
     SORT_STRING: 2
     SORT_LOCALE_STRING: 5
     SORT_NATURAL: 6
     SORT_FLAG_CASE: 8

Great! Let's sort an array in descending order:

     $array = [1, 5, 3];

     sort($array, SORT_DESC);

     echo implode(", ", $array), PHP_EOL;

This code *clearly* prints 5, 3, 1, since `SORT_DESC` is a `SORT_*` constant that is accepted by `sort()` and DESC is a common abbreviation for descending, right?

-----------

Going through an E_WARNING would add maintainer busywork and complicate the php-src codebase for no real gain.

Best regards
Tim Düsterhus

Am 02.03.2026 um 20:12 schrieb Tim Düsterhus <tim@bastelstu.be>:

On 3/2/26 14:49, Christian Schneider wrote:

Playing my favourite broken record:
Can we please state that additions of Exceptions should (in most cases) go through an E_WARNING phase to allow a time window to fix code before changing the behaviour?

“Not passing invalid values” is perfectly backwards compatible. Folks can just fix their code before upgrading their production deployment to the new PHP version, e.g. by trying out the new PHP version in a staging system or running CI for both the old and new PHP version.

- Not everybody has access to a staging system, e.g. people running stuff on hosting services.
- As a hoster I'd rather have a phase where my customers get warnings instead of errors, creates less emergency support load.

In practice an E_WARNING is no less breaking than going straight to an Error, because:
1. The common frameworks include error handlers that just convert any warning and notice to an Exception.

So in that sense there is also no advantage to NOT having a warning phase for those people.
But people treating E_WARNING different from Exceptions (which is probably the exact people whose code breaks with an immediate Exception) do have a time window to fix things.

2. The code is already broken, because it relies on unspecified behavior. The error would just making the user aware that the code is very likely not doing what it appears to be doing based on the input values passed to a function.

It can easily do something valid and ignore the extra bits (pun kind of intended), see
  mkdir("foo", 070777);
which passes extra bits with are ignored but the application was behaving in a completely deterministic and valid way.

Going through an E_WARNING would add maintainer busywork and complicate the php-src codebase for no real gain.

We've been over this before:
If people *really* feel that the additional burden to change the code twice then I'd be happy to volunteer providing a small helper function/macro to generate an E_WARNING and either (the more aggressive approach) switch to an exception once a certain PHP version is reached or (probably the more flexible way) issue a compile time warning/error informing the maintainer to switch the warning to an Exception.
The most simplistic version of this is a FIXME comment annotated with a version number. Easy to grep, easy to trigger automatic alerts about once the specified version is reached, but it can also be something more sophisticated..
One way or the other could also be integrated into the CI/CD system.

Our main disagreement is about the "no real gain" part as it IMHO targets the long tail of PHP code / developers out there not using full-fledged frameworks and dev environments or running legacy software on hosting services.

I am very much in favor of making things easy for the code developers but I am of the strong believe that it can be done in a good way for developers.

Regards,
- Chris

Hi,

On Mon, Mar 2, 2026 at 2:16 PM Gina P. Banyard internals@gpb.moe wrote:

Hello internals,

I would like to propose a short policy RFC to formally exempt input type and value validation from our BC Break policy.
The current wording of the policy already permits us to add validation of inputs, but recently any such changes have been asked to submit an RFC instead.
We believe that requiring an RFC for this type of change is detrimental and adds unnecessary friction for routine maintenance activity and new contributors.

RFC: https://wiki.php.net/rfc/policy-exempt-type-value-error-bc-policy

Message text is fine and it was my omission not to add it as we change it already so thanks for that. It might be good to separate vote for this so it definitely passes.

The ValueError is more problematic because as you can already see with error_log() $message_type, it is not always that straight forward. I would prefer we keep those decided on case by case basis which also gives a better visibility.

Kind regards,

Jakub