====== PHP RFC: Throwable Hierarchy Policy for Extensions ======
  * Version: 1.0
  * Date: 2025-04-27
  * Author: Tim Düsterhus timwolla@php.net, Gina Peter Banyard girgias@php.net
  * Status: Accepted
  * First Published at: https://wiki.php.net/rfc/extension_exceptions

===== Introduction =====

PHP has a number of de facto rules and policies around the use of exceptions in extensions, for example not to use SPL exceptions in new code, but no official de jure policy.

Since a de facto policy depends on someone remembering the policy and bringing it up during discussion based on a collected list of random links, we intend to codify the current de facto policy in the official policies repository.

===== Proposal =====

Accept the policy in https://github.com/php/policies/pull/17.

The described policy is based on the guidelines used for the exceptions introduced in the new ext/random extension in PHP 8.2. ext/random extension is the first self-contained greenfield addition to PHP’s standard library and the first user of PHP’s [[rfc:namespaces_in_bundled_extensions|Namespace Policy]], which allowed for a proper and consistent API design, including the Exception hierarchy. The guidelines used for ext/random’s exception hierachy have since then been used as the basis of the [[rfc:datetime-exceptions|RFC: More Appropriate Date/Time Exceptions]] RFC and the [[rfc:url_parsing_api|Add RFC 3986 and WHATWG compliant URI parsing support]] RFC, making it the current de facto policy for newly designed APIs.

===== Open Issues =====

n/a

===== Proposed Voting Choices =====

<doodle title="Accept php/policies PR #17 (Add Throwable policy) at commit cf4cfb3ea95e3a59a56a395e1fae00ff9722e0cd?" auth="timwolla" voteType="single" closed="true" closeon="2025-05-27T12:30:00Z">
   * Yes
   * No
</doodle>

===== Patches and Tests =====

    * https://github.com/php/policies/pull/17

===== Implementation =====

After the project 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
  - a link to the language specification section (if any)

===== References =====

    * [[https://github.com/php/php-src/pull/9220|Add ext/random Exception hierarchy (PR #9220)]]
    * https://github.com/php/php-src/pull/9071#issuecomment-1193162754
    * [[rfc:datetime-exceptions|RFC: More Appropriate Date/Time Exceptions]]
    * https://externals.io/message/120214#120287
    * https://externals.io/message/123997#127142