[doc-en] master: Document that a return in finally discards a pending exception (#6081)

From: 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>

« previous php.doc.cvs (#23954) next »