Throw exception for invalid characters in number base functions View as Markdown

Accepted
▴ 3 ▾ 0
community vote
Authors
Sjoerd Langkemper sjoerd-php@linuxonly.nl
Date
2026-08-11
Version
0.3
Implementation
https://github.com/php/php-src/pull/22365
Source
wiki.php.net/rfc/throw_error_for_invalid_characters_for_number_base

Vote

Throw a Exception for invalid characters in number base conversion functions? closed
Yes
27
No
1
Abstain
0
28 voters
alexandredaubois Yes 2026-10-16 14:15
ashnazg Yes 2026-10-28 14:40
ayesh Yes 2026-10-16 09:04
crell Yes 2026-10-16 19:29
cschneid Yes 2026-10-16 09:44
daniels Yes 2026-10-19 22:56
duncan3dc Yes 2026-10-16 14:37
dunglas Yes 2026-10-25 13:54
galvao Yes 2026-10-19 00:02
geekcom Yes 2026-10-23 20:32
iliaa Yes 2026-10-16 13:10
jhdxr No 2026-10-21 12:25
jordikroon Yes 2026-10-16 10:05
jorg_sowa Yes 2026-10-21 12:16
josh Yes 2026-10-31 14:16
kalle Yes 2026-10-21 16:49
kguest Yes 2026-10-21 10:56
lufei Yes 2026-10-30 06:07
malferov Yes 2026-10-16 22:06
mbeccati Yes 2026-10-16 17:25
nicolasgrekas Yes 2026-10-21 12:38
ocramius Yes 2026-10-16 21:28
svpernova09 Yes 2026-10-16 13:22
theodorejb Yes 2026-10-16 11:16
thorstenr Yes 2026-10-19 06:07
timwolla Yes 2026-10-16 08:34
weierophinney Yes 2026-10-20 11:44
weilindu Yes 2026-10-16 16:34

Discussions on the mailing list

[RFC] Throw ValueError for invalid characters in number base functions
by Sjoerd Langkemper · 15 messages

RFC text

Copied from wiki.php.net, last synchronized Nov 1, 2026 20:46 UTC

Introduction

Functions that convert numbers from one base to another (bindec(), octdec(), hexdec(), and base_convert()) accept a string representation of a number and convert it. Historically, these functions have been very lenient with their inputs, silently ignoring characters that are invalid for the specified number base.

For example, hexdec('z') treats z as an invalid character, silently ignores it, and returns int(0).

In PHP 7.4, an RFC titled Base Convert Improvements introduced a deprecation notice (E_DEPRECATED) when invalid characters are passed to these functions, with the intention of eventually turning it into an exception in PHP 8. While the deprecation notice was successfully implemented, the exception step was never completed.

This RFC proposes to complete that transition by throwing a Exception when invalid characters are passed to bindec(), octdec(), hexdec(), and base_convert(), starting in PHP 8.7.

Proposal

We propose changing the behavior of bindec(), octdec(), hexdec(), and base_convert() when they encounter characters that are invalid within the context of the requested number base. Instead of emitting a deprecation notice and returning a partial/fallback conversion, these functions will immediately throw a Exception.

Affected functions:

  • bindec() - Binary to decimal
  • octdec() - Octal to decimal
  • hexdec() - Hexadecimal to decimal
  • base_convert() - Convert a number between arbitrary bases

Exception type

Originally the plan was to throw a ValueError. However, ValueError implies that the program has a bug, which is not necessarily the case when an invalid character is passed to one of these functions. Therefore, an Exception (as opposed to Error) seems to better fit.

Examples

Simple example:

<?php
var_dump(hexdec('z'));
 
// PHP 7.4 - 8.6:
// Deprecated: Invalid characters passed for attempted conversion, these have been ignored in ...
// int(0)
 
// PHP 8.7 (Proposed):
// Fatal error: Uncaught Exception: Invalid characters passed for attempted conversion in ...
?>

Error in base_convert depends on the number base:

<?php
base_convert('f', 16, 10);
// 'f' is valid base 16, so no error
 
base_convert('f', 15, 10);
// Fatal error: Uncaught Exception: Invalid characters passed for attempted conversion in ...
?>

Backward Incompatible Changes

Code that relies on the legacy behavior of silently ignoring invalid characters (or catching the current E_DEPRECATED notice) will experience behavior changes. If invalid characters are passed, a Exception will now be thrown, which must be handled using try/catch blocks if invalid inputs are expected from untrusted sources.

Impact

Code that currently relies on the lenient behavior of these functions will fail. I can imagine that legitimate use is primarily having separators in input strings: hexdec('1234-5678'). First, this already throws a deprecation warning since PHP 7.4. Second, this is easily solved with normal string manipulation functions.

Proposed PHP Version(s)

PHP 8.7

Future Scope

Other string-to-number or decoding functions (such as base64_decode(), intval(), etc.) are currently unaffected by this change.

Voting Choices

Vote: Throw a Exception for invalid characters in number base conversion functions (bindec, octdec, hexdec, base_convert) in PHP 8.7? (Yes / No)


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

Vote: Throw a Exception for invalid characters in number base conversion functions? — Yes: 27 · No: 1 · Abstain: 0 (closed)

Patches and Tests

https://github.com/php/php-src/pull/22365

Implementation

After the RFC is implemented, this section should contain:

  1. the version(s) it was merged into
  2. a link to the git commit(s)
  3. a link to the PHP manual entry for the feature

References

Links to external references, discussions, or RFCs.

Rejected Features

There was some talk about throwing a more specific exception than Exception. This is desirable, but there is currently not a good foundation for this. The SPL exceptions (RangeException, UnexpectedValueException) are technically in another extension so may not be thrown from ext/standard. Extensions should specify their own exceptions but exceptions may not be namespaced under Standard. The current proposal of throwing an Exception explicitly makes it possible to make this more specific in the future.

Changelog

If there are major changes to the initial proposal, please include a short summary with a date or a link to the mailing list announcement here, as not everyone has access to the wikis' version history.

  1. 0.3: changed from ValueError to Exception