[doc-en] master: Document that a return in finally discards a pending exception (#6081)
| From: | Asish Kumar via GitHub | Date: | Sat, 14 Nov 2026 17:44:48 +0000 |
| Subject: | [doc-en] master: Document that a return in finally discards a pending exception (#6081) | ||
| Groups: | php.doc.cvs | ||
| Request: | Send a blank email to doc-cvs+get-23954@lists.php.net to get a copy of this message | ||
Author: Asish Kumar (officialasishkumar)
Committer: GitHub (web-flow)
Pusher: lacatoire
Date: 2026-11-14T18:44:45+01:00
Commit: https://github.com/php/doc-en/commit/43127142d0d96b6a49d4bdcc6ca1a72d0e55b7a0
Raw diff: https://github.com/php/doc-en/commit/43127142d0d96b6a49d4bdcc6ca1a72d0e55b7a0.diff
Document that a return in finally discards a pending exception (#6081)
The finally page explained that a return in a finally block overrides
a return from the try or catch block, but not that it also discards an
exception that is being propagated. This is long-standing, intended
behaviour ("finally always wins"), yet an exception rethrown in a catch
block silently disappearing looks like a bug to users.
Document in the return interaction section that a return in finally
discards an uncaught exception from the try block or an exception
thrown or rethrown in a catch block, and that the function returns the
value from finally without reporting an error. Add an example with a
rethrow from catch, checked on PHP 8.4 and 8.5.
Also mention that, unlike return, leaving a finally block with break,
continue or goto is a compile-time fatal error, while loops entirely
inside the finally block can still use break and continue.
Changed paths:
M language/control-structures/finally.xml
Diff:
diff --git a/language/control-structures/finally.xml b/language/control-structures/finally.xml
index 5b3b4dd450a4..04d7fb0adb31 100644
--- a/language/control-structures/finally.xml
+++ b/language/control-structures/finally.xml
@@ -176,6 +176,56 @@ finally catch
]]>
</screen>
</example>
+ <simpara>
+ A &return; statement in a &finally; block also discards any exception that
+ is being propagated when the &finally; block is executed:
+ an exception thrown in the &try; block that is not caught,
+ or an exception thrown or rethrown in a &catch; block.
+ No error is reported, and the function returns the value from the
+ &finally; block as if no exception had been thrown.
+ </simpara>
+ <example>
+ <title>A &return; in a &finally; block discards a rethrown exception</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+function process() {
+ try {
+ throw new Exception('Original exception');
+ } catch (Exception $e) {
+ echo 'Caught: ', $e->getMessage(), "\n";
+ throw $e;
+ } finally {
+ echo 'Within finally', "\n";
+ return 'finally';
+ }
+}
+
+try {
+ echo process(), "\n";
+} catch (Exception $e) {
+ echo 'This is never reached', "\n";
+}
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+Caught: Original exception
+Within finally
+finally
+]]>
+ </screen>
+ </example>
+ <simpara>
+ Unlike &return;, leaving a &finally; block with a
+ <link
linkend="control-structures.break"><literal>break</literal></link>,
+ <link
linkend="control-structures.continue"><literal>continue</literal></link>
+ or <link
linkend="control-structures.goto"><literal>goto</literal></link>
+ statement is not allowed, and results in a compile-time fatal error.
+ Loops entirely contained within the &finally; block may still use
+ <literal>break</literal> and <literal>continue</literal>.
+ </simpara>
</sect2>
<sect2>