# RFC: Throwable Hierarchy Policy for Extensions

- Status: Accepted
- Authors: Tim Düsterhus timwolla@php.net, Gina Peter Banyard girgias@php.net
- Date: 2025-04-27
- Version: 1.0
- Original: https://wiki.php.net/rfc/extension_exceptions
- Page: https://externals.io/rfc/extension_exceptions
- More for agents: search with https://externals.io/search.md?q={query} · RFCs at https://externals.io/rfc.md · JSON API at https://externals.io/api · documentation at https://externals.io/llms.txt

## Votes

### Accept php/policies PR #17 (Add Throwable policy) at commit cf4cfb3ea95e3a59a56a395e1fae00ff9722e0cd? (closed)

Yes: 25 · No: 1

Voters: asgrim (Yes), ayesh (Yes), beberlei (Yes), bwoebi (Yes), cpriest (Yes), crell (Yes), daniels (Yes), derick (Yes), ericmann (Yes), galvao (Yes), girgias (Yes), jimw (Yes), jwage (Yes), kalle (Yes), kguest (Yes), kinncj (Yes), levim (No), mbeccati (Yes), ocramius (Yes), ramsey (Yes), santiagolizardo (Yes), sergey (Yes), theodorejb (Yes), thorstenr (Yes), timwolla (Yes), weierophinney (Yes)

## Discussions on the mailing list

- [\[VOTE\] Use exceptions by default in SQLite3  extension](https://externals.io/message/120214.md) — started on 2023-05-08, 6 messages
- [\[RFC\] \[Discussion\] Add WHATWG compliant URL parsing API](https://externals.io/message/123997.md) — started on 2024-06-28, 149 messages
- [\[RFC\] Throwable Hierarchy Policy for Extensions](https://externals.io/message/127206.md) — started on 2025-04-27, 19 messages
- [\[VOTE\] Throwable Hierarchy Policy for Extensions](https://externals.io/message/127340.md) — started on 2025-05-13, 2 messages

---

## 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](https://externals.io/rfc/namespaces_in_bundled_extensions), 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](https://externals.io/rfc/datetime-exceptions) RFC and the [Add RFC 3986 and WHATWG compliant URI parsing support](https://externals.io/rfc/url_parsing_api) RFC, making it the current de facto policy for newly designed APIs.

## Open Issues

n/a

## Proposed Voting Choices

**Vote: Accept php/policies PR #17 (Add Throwable policy) at commit cf4cfb3ea95e3a59a56a395e1fae00ff9722e0cd?** — Yes: 25 · No: 1 (closed)

## Patches and Tests

- <https://github.com/php/policies/pull/17>

## Implementation

After the project is implemented, this section should contain

1. the version(s) it was merged into
2. a link to the git commit(s)
3. a link to the PHP manual entry for the feature
4. a link to the language specification section (if any)

## References

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