Table of Contents

PHP RFC: Grouped ValueError Conversions for PHP 8.6

Introduction

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.

Proposal

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

Validate the option parameter in mysqli_options() and throw a ValueError for invalid values

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

Implement validation for the option parameter in mysqli_options()? (Restart)
Real name Yes No Abstain
Final result: 0 0 0
This poll has been closed.

Validate the file permission mode in mkdir() and throw a ValueError for invalid values

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
?>
Should mkdir() validate the file permission mode parameter? (Restart)
Real name Yes No Abstain
Final result: 0 0 0
This poll has been closed.

Validate the file permission mode in chmod() and throw a ValueError for invalid values

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
 
?>
Should chmod() validate the permissions parameter? (Restart)
Real name Yes No Abstain
Final result: 0 0 0
This poll has been closed.

Validate the to parameter in copy() and throw a ValueError for invalid values

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
 
?>
Should copy() validate the $to parameter? (Restart)
Real name Yes No Abstain
Final result: 0 0 0
This poll has been closed.

Validate the "message_type" parameter in error_log() and throw a ValueError for invalid values

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
}
?>
Should error_log() validate the $message_type parameter? (Restart)
Real name Yes No Abstain
Final result: 0 0 0
This poll has been closed.

Backward Incompatible Changes

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:

Proposed PHP Version(s)

Next PHP 8.x (target PHP 8.6).

RFC Impact

To the Ecosystem

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

To Existing Extensions

No ABI changes expected.

Extensions may optionally adopt the same validation behavior.

To SAPIs

No impact.

Implementation

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

References

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

Rejected Features

None

Changelog

1.0: Initial version under discussion

1.1: The “message_type” parameter in error_log added

1.2: Vote section added