Refactor error/exception pages into an "Error handling" page#320

Girgias · 2021-01-10T01:37:03Z

This renames traditional errors to diagnostic errors
Attempts to unify Throwable Errors with Exceptions
Move throw, try, catch, and finally control structures to the control structure section

Feedback on this is very welcome and I'm open to suggestion, as some of the text still needs to be updated/improved.
This is partly based on how Rust talks about error handling.

Some ideas I have also been considering:

Split the two section in error-handling.xml into two files in a new subfolder error-handling/

A to-do list of sort:

Trim exception page
Maybe move extending exception page/trim it?
More examples in each specific section.
Create a new page in the control structure section for throw

Memo of things to do when this lands:

Redirect previous pages to the new ones

Girgias · 2021-01-13T14:36:36Z

I think this is now ready for review, I hope I didn't remove any information by splitting it up.

Girgias · 2021-01-13T14:38:36Z

language/error-handling.xml

+  <warning>
+   <para>
+    <classname>Throwable</classname> objects cannot be cloned.
+    Attempting to <link linkend="language.oop5.cloning">clone</link> such an
+    object will result in an <classname>Error</classname> being thrown with
+    the following message:
+    <literal>Trying to clone an uncloneable object of class Exception</literal>.
+   </para>
+  </warning>


I wonder if this warning is relevant here? As it would be pretty unusual to clone an exception, and this behaviour is described on their respective docs.

I agree that this is a generic behavior that is already described in a central location. I see no reason to mention that in every place where it applies. Should the user see such an error, they will be able to find the correct docs through a search.

Firehed · 2021-02-04T20:44:05Z

language/control-structures/finally.xml

+ </example>
+
+ <para>
+  When the call stack is unwound after a <classname>Throwable</classname> error


I think trying to reword this in a way that's more beginner-friendly would be nice. I don't think call stack unwinding is mentioned elsewhere in the docs.

Maybe along the lines of "If there are nested finally blocks, they will be executed in the order they are declared"

I'll keep the technical language (as this is copied from the previous document) but will attempt to add a simpler explanation along side it.

language/control-structures/try-catch.xml

Firehed · 2021-02-04T20:55:02Z

language/error-handling.xml

+ <sect1 xml:id="language.error-handling.throwable">
+  <title><classname>Throwable</classname> errors</title>
+  <para>
+   Most errors in PHP are of this type.


This statement is highly version-specific (without using set_error_handler, at least).

I can add an As of PHP 8, before it, but even in PHP 7 many of the warnings generated by the Engine are catchable Errors

Firehed · 2021-02-04T20:57:21Z

language/error-handling.xml

+    <programlisting role="php">
+<![CDATA[
+<?php
+function exceptions_error_handler($severity, $message, $filename, $lineno) {


I'd argue that doing this is considered best practices by many people. It may be worth calling more attention to this, or adding a best practices section to this document.

Not sure the documentation should decide what are considered best practices, I'll try to emphasis this more however. :-)

language/error-handling.xml

appendices/migration70/incompatible/error-handling.xml

language/control-structures/finally.xml

Crell · 2021-02-14T20:04:19Z

language/control-structures/finally.xml

+<sect1 xml:id="control-structures.finally" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <title>finally</title>
+ <?phpdoc print-version-for="finally"?>
+ <para>


I feel like it would be better to front-load the logic of how finally behaves vis a vis throws, returns, yields, exit, etc., perhaps with a bulleted list, so it's easier to reference. Then proceed with a bunch of examples demonstrating it.

language/control-structures/try-catch.xml

language/error-handling.xml

language/operators.xml

Crell · 2021-02-15T01:21:28Z

Various small issues noted above.

My biggest concern is that this puts exceptions under flow-of-control... but exceptions, as we are told repeatedly, are not meant to be used for flow of control. Yet, they do change the flow of control. My concern is that, without any statement to the contrary, this could tacitly imply that using exceptions the same way you would use if, foreach, or goto is a-OK, when that's very much not the case.

Otherwise, everything else here seems reasonable.

This renames traditional errors to diagnostic errors Create a page about error handling in PHP describing how to handle Throwable Errors (Exceptions) and diagnostics. > Inspired from the Rust docs. Create dedicated pages for: - throw - try-catch - finally

Usage without it is explained in the following section

Also fix part of the set_error_handler() docs

language/error-handling.xml

Co-authored-by: George Peter Banyard <girgias@php.net>

afilina · 2021-08-17T13:30:51Z

@Girgias I resolved the outdated comments and provided my feedback on your own questions. I hope this helps to move this PR forward. I also applied the code suggestion with the syntax fix.

Girgias · 2021-08-17T17:04:14Z

Thanks, I'll try to get back to this, but I need to sort out HTTP redirection for php-web and rebase, I should have time again in September. :-)

afilina · 2022-12-22T16:12:14Z

This branch is getting old and has many merge conflicts. Suggestions:

If conflicts don't require too much effort to resolve, resolve and merge as-is, fixing later as needed.
If too many conflicts, convert it to a checklist ticket, then start new PRs with a smaller change at a time.

afilina · 2023-08-02T16:30:47Z

@Girgias Is it worth to keep this PR open? This looks like a slice that is too big to be feasible. It can be referred to in a ticket (todo) instead, so that you don't lose sight of some of the wording that might be reusable.

Girgias · 2023-08-02T17:37:37Z

@Girgias Is it worth to keep this PR open? This looks like a slice that is too big to be feasible. It can be referred to in a ticket (todo) instead, so that you don't lose sight of some of the wording that might be reusable.

I will try to work on this PR this months as I'm planning to start working on the Migration guide and do more doc works this month (as I also won't have access to my desktop with 24 cores which makes php-src work more annoying)

afilina · 2025-10-13T03:21:26Z

This PR hasn't moved in years. Would it make sense to open a new PR for just the added pages so it can be merged quickly, then work on changing existing pages over time, whenever people have time?

kamil-tekiela · 2025-10-13T11:58:10Z

This PR hasn't moved in years. Would it make sense to open a new PR for just the added pages so it can be merged quickly, then work on changing existing pages over time, whenever people have time?

Yes, reviewing smaller PRs is much easier. There seems to be very little reviewers available anyway, so the easier it is the better.

Girgias force-pushed the refactor-error-page branch from 50e9946 to 116241a Compare January 10, 2021 06:30

Girgias mentioned this pull request Jan 10, 2021

Changes to doc-base for error page refactoring php/doc-base#13

Open

Girgias force-pushed the refactor-error-page branch from 8da7560 to 995807e Compare January 13, 2021 12:51

Girgias changed the title ~~[WIP] Refactor error pages~~ Refactor error/exception pages into an "Error handling" page Jan 13, 2021

Girgias commented Jan 13, 2021

View reviewed changes

Girgias force-pushed the refactor-error-page branch 3 times, most recently from 9c7354a to 3bee578 Compare January 26, 2021 23:23

Firehed reviewed Feb 4, 2021

View reviewed changes

Girgias force-pushed the refactor-error-page branch from 3bee578 to f276137 Compare February 5, 2021 00:12

Girgias mentioned this pull request Feb 8, 2021

Cleanup and update docs related to @ operator #441

Closed

Crell reviewed Feb 14, 2021

View reviewed changes

appendices/migration70/incompatible/error-handling.xml Outdated Show resolved Hide resolved

Crell reviewed Feb 14, 2021

View reviewed changes

language/control-structures/finally.xml Outdated Show resolved Hide resolved

Crell reviewed Feb 14, 2021

View reviewed changes

Crell reviewed Feb 15, 2021

View reviewed changes

language/control-structures/try-catch.xml Outdated Show resolved Hide resolved

Crell reviewed Feb 15, 2021

View reviewed changes

language/error-handling.xml Outdated Show resolved Hide resolved

Crell reviewed Feb 15, 2021

View reviewed changes

language/operators.xml Outdated Show resolved Hide resolved

Girgias added 11 commits February 18, 2021 16:34

Clarify finally and return example

3cf5fb7

Expand finally and exit() interaction section

c40d39b

Indent

5107e89

Make intereaction between return and finally a section

d44b95b

Add an initial section about yield and finally

c29d22f

Clarify what call-stack unwinding means

87410c4

Use variable in catch statement

1a5cbea

Usage without it is explained in the following section

Add error_reporting() check when using a custom error handler

92edebf

Cleanup docs related to @ operator

14f3c00

Also fix part of the set_error_handler() docs

Nits

10c5c67

Girgias added 2 commits February 18, 2021 16:55

Front load logic of finally behaviour with various other bits

be58da6

Document weird finally exit and generator edge case

0b089b1

Girgias force-pushed the refactor-error-page branch from f276137 to 0b089b1 Compare February 18, 2021 17:09

Girgias commented Mar 25, 2021

View reviewed changes

language/error-handling.xml Outdated Show resolved Hide resolved

Add missing parenthesis

09aa2d8

Co-authored-by: George Peter Banyard <girgias@php.net>

afilina added the Waiting on Author label Aug 17, 2021

Girgias mentioned this pull request Nov 10, 2022

Change simplesect to sect1 in exception chapter #1988

Merged

iluuu1994 requested review from kamil-tekiela and ndossche as code owners April 15, 2025 14:20

afilina mentioned this pull request Oct 15, 2025

Refactor error pages, minus the merge conflicts #4931

Open

Conversation

Girgias commented Jan 10, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Girgias commented Jan 13, 2021

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Crell commented Feb 15, 2021

Uh oh!

Uh oh!

afilina commented Aug 17, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Girgias commented Aug 17, 2021

Uh oh!

afilina commented Dec 22, 2022

Uh oh!

afilina commented Aug 2, 2023

Uh oh!

Girgias commented Aug 2, 2023

Uh oh!

afilina commented Oct 13, 2025

Uh oh!

kamil-tekiela commented Oct 13, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Girgias commented Jan 10, 2021 •

edited

Loading

afilina commented Aug 17, 2021 •

edited

Loading