PHP RFC: Throwable Hierarchy Policy for Extensions
- Version: 1.0
- Date: 2025-04-27
- Author: Tim Düsterhus [email protected], Gina Peter Banyard [email protected]
- Status: Under Discussion
- 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 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: More Appropriate Date/Time Exceptions RFC and the 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
Patches and Tests
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)