Everything

php

[RFC] Throw ValueError for invalid characters in number base functions

php.internals

Sjoerd Langkemper

4 days ago

Hello,

Next Friday I'll open the vote for the RFC for Throw ValueError for invalid characters in number base functions.

RFC: https://wiki.php.net/rfc/throw_error_for_invalid_characters_for_number_base
Earlier RFCs:
* https://wiki.php.net/rfc/php86_valueerror_conversions#throw_error_for_invalid_characters_for_number_base
* https://wiki.php.net/rfc/base_convert_improvements
Earlier discussions:
* https://news-web.php.net/php.internals/131448
* https://news-web.php.net/php.internals/104618
* https://news-web.php.net/php.internals/105740
PR: https://github.com/php/php-src/pull/22365

This will throw an error for octdec, hexdec, bindec and base_convert on invalid input. We already agreed to this before (in RFC base_convert changes), so this RFC is not really controversial but more about following the right procedure.

Regards,

Sjoerd Langkemper

Tim Düsterhus

1 day ago

Hi

On 2026-08-28 10:24, Sjoerd Langkemper wrote:

> Next Friday I'll open the vote for the RFC for Throw ValueError for
> invalid characters in number base functions.

From what I see this is the first email regarding this RFC, the archives
do not show any previous emails in the discussion thread:
https://news-web.php.net/php.internals/132379. New RFCs require a
minimum discussion period of 14 days before they may go to voting.

> This will throw an error for octdec, hexdec, bindec and base_convert on
> invalid input. We already agreed to this before (in RFC base_convert
> changes), so this RFC is not really controversial but more about
> following the right procedure.

I'm not sure ValueError is the correct throwable to use here: I believe
passing “user-provided” inputs to these methods might be an expected use
case, where developers would then be interested in catching the
resulting exception as an implicit validation mechanism. This is also
acknowledged by the RFC:

> If invalid characters are passed, a ValueError will now be thrown,
> which must be handled using try/catch blocks if invalid inputs are
> expected from untrusted sources.

The Error hierarchy is not intended to be caught, though. It should thus
use something from the Exception hierarchy.

Best regards
Tim Düsterhus

Sjoerd Langkemper

1 day ago

On Mon, Aug 31, 2026, at 11:05, Tim Düsterhus wrote:

> > This will throw an error for octdec, hexdec, bindec and base_convert on
> > invalid input.
>
> I'm not sure ValueError is the correct throwable to use here: I believe
> passing “user-provided” inputs to these methods might be an expected use
> case, where developers would then be interested in catching the
> resulting exception as an implicit validation mechanism. This is also
> acknowledged by the RFC: ...
>
> The Error hierarchy is not intended to be caught, though. It should thus
> use something from the Exception hierarchy.

I wasn't aware of a distinction between error and exception objects like this. Is this documented somewhere? Is there a policy when to throw errors and when to throw exceptions? Does the documentation describe that developers should only catch exceptions and not errors?

Why would these functions be used for user input more often than other functions? How can we determine whether a function should throw an exception or an error?

I think ValueError is still the right thing to throw.

On Mon, Aug 31, 2026, at 11:05, Tim Düsterhus wrote:

> On 2026-08-28 10:24, Sjoerd Langkemper wrote:
> > Next Friday I'll open the vote for the RFC for Throw ValueError for
> > invalid characters in number base functions.
>
> From what I see this is the first email regarding this RFC

The RFC was announced here: https://news-web.php.net/php.internals/132219

And before that the same idea in another RFC: https://news-web.php.net/php.internals/131448

This gave more than a month to respond to the proposal, and exactly two weaks for responding to the exact RFC.

Regards,

Sjoerd

Tim Düsterhus

1 day ago

Hi

On 2026-08-31 15:36, Sjoerd Langkemper wrote:

>> The Error hierarchy is not intended to be caught, though. It should
>> thus
>> use something from the Exception hierarchy.
>
> I wasn't aware of a distinction between error and exception objects
> like this. Is this documented somewhere? Is there a policy when to
> throw errors and when to throw exceptions?

Yes, in:
https://github.com/php/policies/blob/main/coding-standards-and-naming.rst#throwables

Specifically:

> The Error hierarchy MUST NOT be used for errors that are expected to be
> thrown (and caught) during normal operation of a PHP program.
>
> As an example, a parsing function that is expected to be used with
> untrusted input must not throw an Error if the input is malformed.
> Similarly a function that interacts with the network must not throw an
> Error if the network operation fails. Any Error that is thrown should
> usually result in a reasonably obvious fix in the PHP program.

> Why would these functions be used for user input more often than other
> functions? How can we determine whether a function should throw an
> exception or an error?

The quoted policy provides some examples. I'd argue that “base
conversion” falls into the “parsing function” category, because it needs
to parse the inputs. It is unreasonable for the user to perform a
pre-validation, because that effectively means reimplementing large
parts of the logic of the conversion functions.

>> > Next Friday I'll open the vote for the RFC for Throw ValueError for
>> > invalid characters in number base functions.
>>
>> From what I see this is the first email regarding this RFC
>
> The RFC was announced here:
> https://news-web.php.net/php.internals/132219

Ah. That email was a reply to an existing discussion thread though and
thus didn't create a proper top-level discussion for the RFC.

> This gave more than a month to respond to the proposal, and exactly two
> weaks for responding to the exact RFC.

Due to the above it is likely that the email was collapsed into the
discussion thread without the [RFC] tag and was thus missed by mailing
list participants - as was the case for me.

Best regards
Tim Düsterhus