Skip to content

Remove unnecessary backslash in \DivisionByZeroError , and 2 rare instances of mixed \Exception and Exception in the finally documentation (fully qualified names used unnecessarily in examples without namespaces) - #5947

Merged
lacatoire merged 1 commit into
php:masterfrom
willy-b:fix-more-inconsistent-fully-qualified-name-usage-for-exceptions
Oct 14, 2026

Conversation

@willy-b

@willy-b willy-b commented Oct 13, 2026

Copy link
Copy Markdown
Contributor

(No AI or LLM assistance was used in finding this nor in preparing the commit/PR.)

Hello PHP team!
Thanks again for the excellent documentation.

This follows up on #5928 for the match page,
and fixes some more rare and unnecessary usage of the fully qualified "\Exception" form for Exceptions or Errors on the finally page ( https://web.archive.org/web/20261013211124/https://www.php.net/manual/en/control-structures.finally.php ), which might confuse readers as it is before the concept of namespaces and such fully qualified names are introduced in the documentation (see https://www.php.net/manual/en/language.namespaces.faq.php#language.namespaces.faq.qualified#:~:text=Fully%20Qualified%20names , archived as is at https://web.archive.org/web/20261011041428/https://www.php.net/manual/en/language.namespaces.faq.php#:~:text=Fully%20Qualified%20names ). (Note that the current try-catch documentation does not use the fully qualified names for any Exception/Error classes, see https://web.archive.org/web/20261011043514/https://www.php.net/manual/en/control-structures.try-catch.php#:~:text=catch%20(Exception%20$e) .)

Most of the "Exception" instances on the page, e.g. Example 2, Example 3 , Example 4, Example 5, Example 9 are not using the fully qualified name.

This fixes the few usages occurring in Example 1 where there are two instances of \DivisionByZeroError , e.g. at
\DivisionByZeroError , and also three \Exception usages inconsistent with the others (unnecessary and again before namespaces are introduced so could confuse readers), where there are inner and outer Exception catch blocks and the inner catch is using \Exception, but such a construction does not require this.

E.g. Example 6 had two instances of catch (Exception $e) in the same example, both referring to the same class but one using the fully qualified and one not: https://web.archive.org/web/20261013211124/https://www.php.net/manual/en/control-structures.finally.php#:~:text=Example%20#6

Example # 6 finally block being run when an Exception has been thrown

<?php
function generate()
{
   try {
       yield 1;
       yield 2;
   } catch (\Exception $e) { // <-- inconsistent with the 2nd usage in same example, using unnecessary fully qualified name here
       echo 'catch';
   } finally {
       echo "finally\n";
   }
}

try {
   foreach (generate() as $i) {
       echo , "\n";
       throw new Exception();
   }
} catch (Exception $e) { // <-- most usages are just the class name
   echo 'outer catch';
}

In the above the "outer catch" uses "Exception" and the "inner catch" uses "\Exception" but the outer/inner function scope distinction here does not require switching to the fully qualified name. The same confusion repeats in Example #7, https://web.archive.org/web/20261013211124/https://www.php.net/manual/en/control-structures.finally.php#:~:text=Example%20#7 . and one more time in "Edge case of calling exit() in a foreach over a generator" https://web.archive.org/web/20261013211124/https://www.php.net/manual/en/control-structures.finally.php#:~:text=Edge%20case%20of%20calling%20exit()%20in%20a%20foreach%20over%20a%20generator .

Thanks so much!

…tances of mixed \Exception and Exception in the finally documentation (fully qualified name used unnecessarily in an example without namespaces)

Continues the change made for the match documentation at php@957f7af for the finally documentation.

In https://web.archive.org/web/20261013211124/https://www.php.net/manual/en/control-structures.finally.php#:~:text=Throwable%20error%20handling%20with%20a%20finally%20block
there were two instances of "\DivisionByZeroError" )
e.g.
https://web.archive.org/web/20261013211124/https://www.php.net/manual/en/control-structures.finally.php#:~:text=\DivisionByZeroError

inconsistent with the use of MOST of the "Exception" usage on the page,
e.g. Example # 2, https://web.archive.org/web/20261013211124/https://www.php.net/manual/en/control-structures.finally.php#:~:text=All%20finally%20blocks%20will%20be%20executed ,
Example # 3, https://web.archive.org/web/20261013211124/https://www.php.net/manual/en/control-structures.finally.php#:~:text=Example%20#3 ,
Example # 4, https://web.archive.org/web/20261013211124/https://www.php.net/manual/en/control-structures.finally.php#:~:text=Example%20#4 ,
Example # 5, https://web.archive.org/web/20261013211124/https://www.php.net/manual/en/control-structures.finally.php#:~:text=Example%20#5 ,
Example # 9, https://web.archive.org/web/20261013211124/https://www.php.net/manual/en/control-structures.finally.php#:~:text=Example%20#9 .

There were also three "\Exception" usages inconsistent with the others (unnecessary and again before namespaces are introduced so could confuse readers),
where there are inner and outer Exception catch blocks and the inner catch is using "\Exception", but such a construction does not require this.

E.g. Example 6 has two instances of `catch (Exception $e)` in the same example, both referring to the same class but one using the fully qualified and one not:
https://web.archive.org/web/20261013211124/https://www.php.net/manual/en/control-structures.finally.php#:~:text=Example%20#6

>```
> <?php
> function generate()
> {
>    try {
>        yield 1;
>        yield 2;
>    } catch (\Exception $e) {
>        echo 'catch';
>    } finally {
>        echo "finally\n";
>    }
>}
>
>try {
>    foreach (generate() as $i) {
>        echo , "\n";
>        throw new Exception();
>    }
>} catch (Exception $e) {
>    echo 'outer catch';
>}
>```

In the above the "outer catch" uses "Exception" and the "inner catch" uses "\Exception" but the outer/inner function scope distinction here does not require switching to the fully qualified name.
The same confusion repeats in Example php#7, https://web.archive.org/web/20261013211124/https://www.php.net/manual/en/control-structures.finally.php#:~:text=Example%20#7 .
and one more time in "Edge case of calling exit() in a foreach over a generator"
https://web.archive.org/web/20261013211124/https://www.php.net/manual/en/control-structures.finally.php#:~:text=Edge%20case%20of%20calling%20exit()%20in%20a%20foreach%20over%20a%20generator .

This commit standardizes the usage on this page and avoids possible confusion for readers as namespaces and the fully qualified name notation has not been discussed yet at this point in the documentation.

(No AI or LLM assistance was used in finding this nor in preparing the commit/PR.)
@lacatoire
lacatoire merged commit 6af4cd5 into php:master Oct 14, 2026
3 checks passed
@jordikroon

Copy link
Copy Markdown
Member

Thank you @willy-b. Just a quick note; For these kind of PRs a short description is more than sufficient. It will (hopefully) save you some time in the future.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants