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

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

chmod("file.txt", 99999); // invalid mode

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

?>
</PHP>

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

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


==== Examples ====

Invalid chmod() and mkdir() mode value:

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

?>
</PHP>
 


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

The migration guide will list affected functions.

==== To Existing Extensions ====
No ABI changes expected.

Extensions may optionally adopt the same validation behavior.

==== To SAPIs ====
No impact.

===== Open Issues =====
Final list of functions to convert.

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

===== Future Scope =====
Future RFCs may:

Continue remaining warning → exception conversions

Standardize argument validation across all extensions


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

Please consult [[https://github.com/php/policies/blob/main/feature-proposals.rst#voting-phase|the php/policies repository]] for the current voting guidelines.

----

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

<doodle title="Implement $feature as outlined in the RFC?" voteType="single" closed="true" closeon="2026-01-01T15:30:00Z">
   * Yes
   * No
   * Abstain
</doodle>

===== Patches and Tests =====
Initial patch:
https://github.com/php/php-src/pull/21152

More PRs will be added before the final vote.

===== Implementation =====
After the RFC is implemented, this section should contain:
  - the version(s) it was merged into
  - a link to the git commit(s)
  - a link to the PHP manual entry for the feature

===== References =====
Links to external references, discussions, or RFCs.

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

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