====== 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:
    * [[https://github.com/php/php-src/pull/20971|Validate the option parameter in mysqli_options()]]
    * [[https://github.com/php/php-src/pull/21152|Validate the file permission mode in mkdir()]]
    * [[https://github.com/php/php-src/pull/21214|Validate the to parameter in copy()]]

===== 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 <php>ValueError</php>. Detailed explanations are provided in the Proposal section.

    * Validate the option parameter in <php>mysqli_options()</php> and throw a <php>ValueError</php> for invalid values.
    * Validate the file permission mode in <php>mkdir()</php> and throw a <php>ValueError</php> for invalid values.
    * Validate the file permission mode in <php>chmod()</php> and throw a <php>ValueError</php> for invalid values.
    * Validate the "to" parameter in <php>copy()</php> and throw a <php>ValueError</php> for invalid values.
    * Validate the "message_type" parameter in <php>error_log()</php> and throw a <php>ValueError</php> for invalid values.
 

===== 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 ====

  * Author: Muhammed Arshid <arshidkv12@gmail.com>

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

<PHP> <?php

$mysqli = new mysqli();
$value = $mysqli->options(-1, 'invalid_option');
var_dump($value);

// PHP ≤ 8.5: return false
// PHP 8.6 (proposed): ValueError exception

?>
</PHP>
Implementation PR: https://github.com/php/php-src/pull/20971

<doodle title="Implement validation for the option parameter in mysqli_options()? (Restart)" voteType="single" closed="true" closeon="2026-03-17T16:30:00Z">
   * Yes
   * No
   * Abstain
</doodle>

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

  * Author: Muhammed Arshid <arshidkv12@gmail.com>

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

<PHP> <?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
?>
</PHP>

<doodle title="Should mkdir() validate the file permission mode parameter? (Restart)" voteType="single" closed="true" closeon="2026-03-17T16:30:00Z">
   * Yes
   * No
   * Abstain
</doodle>

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

    * Author: Muhammed Arshid arshidkv12@gmail.com

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

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

?>
</PHP>

<doodle title="Should chmod() validate the permissions parameter? (Restart)" voteType="single" closed="true" closeon="2026-03-17T16:30:00Z">
   * Yes
   * No
   * Abstain
</doodle>

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

?>
</PHP>

<doodle title="Should copy() validate the $to parameter? (Restart)" voteType="single" closed="true" closeon="2026-03-17T16:30:00Z">
   * Yes
   * No
   * Abstain
</doodle>

==== 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> <?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
}
?>
</PHP>

<doodle title="Should error_log() validate the $message_type parameter? (Restart)" voteType="single" closed="true" closeon="2026-03-17T16:30:00Z">
   * Yes
   * No
   * Abstain
</doodle>

===== Backward Incompatible Changes =====

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

Example breakage:

<PHP>
<?php

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

?>
</PHP>

Fix:

<PHP>
<?php

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

?>
</PHP>

Impact expected to be low because:

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

===== 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:
  - the version(s) it was merged into: 8.6
  - a link to the git commit(s)
  - 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