PHP RFC: Throw exception for invalid characters in number base functions

• Version: 0.3
• Date: 2026-08-11
• Author: Sjoerd Langkemper sjoerd-php@linuxonly.nl
• Status: Under discussion
• Implementation: https://github.com/php/php-src/pull/22365
• Earlier RFC: Grouped ValueError Conversions for PHP 8.6, Throw error for invalid characters for number base
• Discussion thread:
  • https://news-web.php.net/php.internals/131448
  • https://news-web.php.net/php.internals/104618
  • https://news-web.php.net/php.internals/105740
  • https://news-web.php.net/php.internals/132379
• Voting thread: tbd

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.

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

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.

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

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.

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.

PHP 8.7

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

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:

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

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

Links to external references, discussions, or RFCs.

Keep this updated with features that were discussed on the mail lists.

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