PHP RFC: Grouped ValueError Conversions for PHP 8.6

• Version: 0.9
• Date: 2026-01-01
• Author: Muhammed Arshid KV, arshidkv12@gmail.com
• Status: Draft
• Implementation: https://github.com/php/php-src/pull/21152

Many PHP internal functions currently emit warnings and return false when invalid argument values are passed. Modern PHP prefers throwing ValueError for invalid inputs.

This RFC groups multiple similar changes into one proposal for PHP 8.6 to keep behavior consistent and simplify migration documentation.

Example:

 <?php
 
chmod("file.txt", 99999); // invalid mode
 
// PHP ≤ 8.5: return false
// PHP 8.6 (proposed): ValueError exception
 
?>

Example implementation PR: https://github.com/php/php-src/pull/21152

For PHP 8.6, convert selected internal functions so that invalid argument values throw ValueError instead of returning false.

Scope includes:

• Invalid range checks
• Invalid enum/flag values
• Invalid parameter formats

Invalid chmod() and mkdir() mode value:

<?php
 
// ----- chmod() -----
 
// Before (current behavior)
var_dump(chmod("file.txt", 99999)); // bool(false)
 
// After (proposed behavior)
try {
    chmod("file.txt", 99999);
} catch (ValueError $e) {
    echo $e->getMessage();
    // Example:
    // chmod(): Argument #2 ($mode) must be between 0 and 07777
}
 
 
// ----- mkdir() -----
 
// Before (current behavior)
var_dump(mkdir("testdir", 99999)); // bool(false)
 
// After (proposed behavior)
try {
    mkdir("testdir", 99999);
} catch (ValueError $e) {
    echo $e->getMessage();
    // Example:
    // mkdir(): Argument #2 ($mode) must be between 0 and 07777
}
 
?>

Code that relied on chmod() returning false for invalid mode values will now throw a ValueError.

Example breakage:

<?php
 
chmod("file.txt", 99999);
// Previously returned false, now throws ValueError
 
?>

Fix:

<?php
 
try {
    chmod("file.txt", 99999);
} catch (ValueError $e) {
    // Handle error
}
 
?>

Impact expected to be low because:

• Most code already checks return values
• Invalid argument values are rare in correct programs

Next PHP 8.x (target PHP 8.6).

IDEs, static analyzers, and linters may update rules to detect possible ValueError throws.

The migration guide will list affected functions.

No ABI changes expected.

Extensions may optionally adopt the same validation behavior.

No impact.

Final list of functions to convert.

Whether to include filesystem functions only in this RFC or others too.

Future RFCs may:

Continue remaining warning → exception conversions

Standardize argument validation across all extensions

Pick a title that reflects the concrete choice people will vote on.

Please consult the php/policies repository for the current voting guidelines.

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

Initial patch: https://github.com/php/php-src/pull/21152

More PRs will be added before the final vote.

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.