PHP RFC: Grouped ValueError Conversions for PHP 8.6

• Version: 0.9
• Date: 2026-19-02
• Author: Muhammed Arshid KV, arshidkv12@gmail.com
• Status: Under Discussion
• Implementation:
  • Validate the option parameter in mysqli_options()
  • Validate the file permission mode in mkdir()
  • Validate the to parameter in copy()

Many PHP internal functions currently 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.

The following list provides a brief overview of the functionality for which invalid arguments are proposed to throw ValueError. Detailed explanations are provided in the Proposal section.

• Validate the option parameter in mysqli_options() and throw a ValueError for invalid values.
• Validate the file permission mode in mkdir() and throw a ValueError for invalid values.
• Validate the file permission mode in chmod() and throw a ValueError for invalid values.
• Validate the “to” parameter in copy() and throw a ValueError for invalid values.
• Validate the “message_type” parameter in error_log() and throw a ValueError for invalid values.

Each feature proposed for deprecation will be voted on separately and requires a 2/3 majority to pass.

• Author: Muhammed Arshid arshidkv12@gmail.com

This proposal validates the option parameter of mysqli_options() and throws a ValueError when an invalid option is provided, instead of emitting a returning false.

 <?php
 
$mysqli = new mysqli();
$value = $mysqli->options(-1, 'invalid_option');
var_dump($value);
 
// PHP ≤ 8.5: return false
// PHP 8.6 (proposed): ValueError exception
 
?>

Implementation PR: https://github.com/php/php-src/pull/20971

• Author: Muhammed Arshid arshidkv12@gmail.com

Throw a ValueError when mkdir() is called with an invalid file permission mode.

 <?php
 
// Current behavior
var_dump(mkdir("testdir", 99999)); // bool(false)
 
// After (proposed behavior)
try {
    mkdir("testdir", 99999);
} catch (ValueError $e) {
    echo $e->getMessage();
    // mkdir(): Argument #2 ($mode) must be between 0 and 0o7777
}
 
// PHP ≤ 8.5: return false
// PHP 8.6 (proposed): ValueError exception
?>

• Author: Muhammed Arshid arshidkv12@gmail.com

Throw a ValueError when chmod() is called with an invalid file permission mode.

 <?php
 
// Current behavior
var_dump(chmod("file.txt", 99999)); // bool(false)
 
// After (proposed behavior)
try {
chmod("file.txt", 99999);
} catch (ValueError $e) {
echo $e->getMessage();
// chmod(): Argument #2 ($mode) must be between 0 and 0o7777
}
 
// PHP ≤ 8.5: return false
// PHP 8.6 (proposed): ValueError exception
 
?>

Author: Muhammed Arshid arshidkv12@gmail.com

Throw a ValueError when copy() is called with an invalid to parameter.

 <?php
 
// Current behavior (may hang on some systems, e.g. macOS)
var_dump(copy("source.txt", "")); // bool(false)
 
// After (proposed behavior)
try {
copy("source.txt", "");
} catch (ValueError $e) {
echo $e->getMessage();
// copy(): Argument #2 ($to) must be a non-empty valid path
}
 
// PHP ≤ 8.5: return false
// PHP 8.6 (proposed): ValueError exception
 
?>

Author: Muhammed Arshid arshidkv12@gmail.com

Throw a ValueError when error_log() is called with an invalid to parameter.

 <?php
 
// Current behavior
error_log('', 42); //bool(true)
 
// After (proposed behavior)
try {
  error_log('', 42);
} catch (ValueError $e) {
echo $e->getMessage();
// error_log(): Argument #2 ($message_type) must be an integer between 0 and 4
}
?>

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.

No ABI changes expected.

Extensions may optionally adopt the same validation behavior.

No impact.

After the RFC is implemented, this section should contain:

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

Current discussion: https://externals.io/message/130090

None

1.0: Initial version under discussion

1.1: The “message_type” parameter in error_log added

1.2: Vote section added