rfc:suppressed_exceptions
Differences
This shows you the differences between two versions of the page.
Next revision | Previous revision | ||
rfc:suppressed_exceptions [2019/04/04 16:36] – Updated RFC to reflect 2/3 majority required. danack | rfc:suppressed_exceptions [2019/04/04 17:43] (current) – danack | ||
---|---|---|---|
Line 1: | Line 1: | ||
- | ====== PHP RFC: Your Title Here ====== | + | ====== PHP RFC: Suppressed Exceptions |
- | * Version: 0.9 | + | * Version: 0.1 |
- | * Date: 2013-02-24 (use today' | + | * Date: 2019-04-04 |
- | * Author: | + | * Author: |
- | * Status: Draft (or Under Discussion or Accepted or Declined) | + | * Status: Draft |
- | * First Published at: http:// | + | * First Published at: https:// |
- | This is a suggested template for PHP Request for Comments (RFCs). Change this template to suit your RFC. Not all RFCs need to be tightly specified. | + | ===== Introduction ===== |
- | Read https:// | + | |
+ | Currently in PHP there are some scenarios where information about exceptions can be lost, particularly when multiple exceptions occur in block of code. For example when retrying network requests. | ||
- | Quoting [[http:// | + | < |
+ | function fetchDataOverNetwork() { | ||
- | > PHP is and should remain: | + | for ($i = 0; $i < MAX_ATTEMPTS; |
- | > 1) a pragmatic web-focused language | + | try { |
- | > 2) a loosely typed language | + | // Some operation that may throw |
- | > 3) a language which caters | + | return foo(); |
+ | } | ||
+ | catch (NetworkException $networkException) { | ||
+ | // can't do anything with $networkException here | ||
+ | } | ||
+ | } | ||
+ | |||
+ | // Information about $networkExceptions is lost. | ||
+ | throw new FetchDataException(" | ||
+ | } | ||
+ | </code> | ||
+ | |||
+ | Another example where an exception | ||
+ | |||
+ | <code php> | ||
+ | $resource = acquireSomeResource(); | ||
+ | |||
+ | try { | ||
+ | foo($resource); | ||
+ | } | ||
+ | catch (FooException $fooException) { | ||
+ | try { | ||
+ | // try to release resource cleanly | ||
+ | $resource-> | ||
+ | throw $fooException; | ||
+ | } | ||
+ | catch (ResourceException $resourceException) { | ||
+ | // The information about $resourceException is lost. | ||
+ | throw $fooException; | ||
+ | } | ||
+ | } | ||
+ | |||
+ | </ | ||
+ | |||
+ | |||
+ | Although PHP has the capability | ||
+ | |||
+ | Additionally the ' | ||
- | Your RFC should move PHP forward following his vision. As [[http:// | ||
- | large chunk of our userbase, and not something that could be useful in some | ||
- | extremely specialized edge cases [...] Make sure you think about the full context, the huge audience out there, the consequences of making the learning curve steeper with | ||
- | every new feature, and the scope of the goodness that those new features bring." | ||
- | ===== Introduction ===== | ||
- | The elevator pitch for the RFC. The first paragraph of this section will be slightly larger to give it emphasis; please write a good introduction. | ||
===== Proposal ===== | ===== Proposal ===== | ||
- | All the features and examples of the proposal. | ||
- | To [[http:// | + | This RFC proposes |
- | for inclusion in one of the world' | + | |
- | Remember that the RFC contents should be easily reusable in the PHP Documentation. | ||
- | If applicable, you may wish to use the language specification as a reference. | + | <code php> |
+ | public void addSuppressed(Throwable exception); | ||
- | ===== Backward Incompatible Changes ===== | + | public getSuppressed(): |
- | What breaks, and what is the justification for it? | + | </ |
- | ===== Proposed PHP Version(s) ===== | + | These signatures would be similar to those in [Java](https:// |
- | List the proposed PHP versions that the feature will be included | + | |
- | ===== RFC Impact ===== | ||
- | ==== To SAPIs ==== | ||
- | Describe the impact to CLI, Development web server, embedded PHP etc. | ||
- | ==== To Existing Extensions ==== | + | These suppressed exceptions can be handled or logged appropriately where the exception is caught. |
- | Will existing extensions | + | |
- | ==== To Opcache ==== | ||
- | It is necessary to develop RFC's with opcache in mind, since opcache is a core extension distributed with PHP. | ||
- | Please explain how you have verified your RFC's compatibility with opcache. | ||
- | ==== New Constants ==== | + | Example when retrying network requests. |
- | Describe any new constants so they can be accurately and comprehensively explained in the PHP documentation. | + | |
- | ==== php.ini Defaults ==== | + | < |
- | If there are any php.ini settings then list: | + | function fetchDataOverNetwork() { |
- | * hardcoded default values | + | |
- | * php.ini-development values | + | |
- | * php.ini-production values | + | |
- | ===== Open Issues ===== | + | $networkExceptions |
- | Make sure there are no open issues when the vote starts! | + | |
- | ===== Unaffected PHP Functionality ===== | + | for ($i = 0; $i < MAX_ATTEMPTS; |
- | List existing areas/features of PHP that will not be changed by the RFC. | + | try { |
+ | | ||
+ | return foo(); | ||
+ | } | ||
+ | catch (NetworkException $ne) { | ||
+ | $networkExceptions[] = $ne; | ||
+ | } | ||
+ | } | ||
- | This helps avoid any ambiguity, shows that you have thought deeply about the RFC's impact, and helps reduces mail list noise. | + | $fdException = new FetchDataException(" |
+ | |||
+ | foreach ($networkExceptions as $networkException) { | ||
+ | $fdException-> | ||
+ | } | ||
+ | |||
+ | throw $fdException; | ||
+ | } | ||
+ | </ | ||
- | ===== Future Scope ===== | + | |
- | This section details areas where the feature might be improved | + | Example when cleaning up resource |
+ | <code php> | ||
+ | $resource | ||
+ | |||
+ | try { | ||
+ | foo($resource); | ||
+ | } | ||
+ | catch (FooException $fooException) { | ||
+ | try { | ||
+ | // try to release resource cleanly | ||
+ | $resource-> | ||
+ | throw $fe; | ||
+ | } | ||
+ | catch (ResourceException $resourceException) { | ||
+ | $fe-> | ||
+ | throw $fooException; | ||
+ | } | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | |||
+ | ===== Why not add suppressed in constructor? | ||
+ | |||
+ | As per the resource exception sometimes it is necessary to add suppressed exception to an exception that has been caught and is going to be re-thrown. | ||
+ | |||
+ | |||
+ | ===== Why not just use the ' | ||
+ | |||
+ | The constructor for Exceptions allows a ' | ||
+ | |||
+ | <code php> | ||
+ | function foo() | ||
+ | { | ||
+ | try { | ||
+ | bar(); | ||
+ | } | ||
+ | // LogicException is part of core | ||
+ | catch (LogicException $le) { | ||
+ | throw new FooException( | ||
+ | " | ||
+ | 0, | ||
+ | $le | ||
+ | ) | ||
+ | } | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | In this example, only one thing has gone wrong unexpectedly and so the FooException and LogicException are representing a single unexpected error. As it is a single error, this exception only needs to be logged once. | ||
+ | |||
+ | In the resource exception example, the fact that there was an exception calling ' | ||
+ | |||
+ | |||
+ | |||
+ | |||
+ | Additionally, | ||
+ | |||
+ | |||
+ | ===== Backward Incompatible Changes ===== | ||
+ | |||
+ | This has the potential to break user's custom exception serializing and deserializing. Although individually these would not be major breaks, they would still be more appropriate to have at a major release than a minor release, hence this RFC targets PHP 8. | ||
+ | |||
+ | ===== Proposed PHP Version(s) ===== | ||
+ | |||
+ | 8 | ||
===== Proposed Voting Choices ===== | ===== Proposed Voting Choices ===== | ||
- | Include these so readers know where you are heading and can discuss the proposed voting options. | ||
- | The primary vote of an RFC requires a 2/3 majority. | + | Single for requiring |
- | ===== Patches and Tests ===== | ||
- | Links to any external patches and tests go here. | ||
- | If there is no patch, make it clear who will create a patch, or whether a volunteer to help with implementation is needed. | ||
- | Make it clear if the patch is intended to be the final patch, or is just a prototype. | ||
- | For changes affecting the core language, you should also provide a patch for the language specification. | ||
- | ===== Implementation ===== | ||
- | After the project is implemented, | ||
- | - 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 ===== | ||
- | Links to external references, discussions or RFCs | ||
- | ===== Rejected Features | + | |
- | Keep this updated with features that were discussed on the mail lists. | + | |
+ | ===== Patches and Tests ===== | ||
+ | TODO . | ||
+ | |||
+ | ===== Implementation ===== | ||
+ | TODO |
rfc/suppressed_exceptions.1554395769.txt.gz · Last modified: 2019/04/04 16:36 by danack