[doc-en] master: Restructure error handling and remove duplication (#5943)

Author: Kamil Tekiela (kamil-tekiela) Committer: GitHub (web-flow) Pusher: kamil-tekiela Date: 2026-10-13T17:05:01+01:00 Commit: https://github.com/php/doc-en/commit/6b099f8dcc7a8f4a6863a6149d7cd97c7f43c470 Raw diff: https://github.com/php/doc-en/commit/6b099f8dcc7a8f4a6863a6149d7cd97c7f43c470.diff Restructure error handling and remove duplication (#5943) Changed paths: M language/control-structures/throw.xml M language/control-structures/try-catch.xml M language/error-handling.xml M language/predefined/error/clone.xml M language/predefined/exception/clone.xml Diff: diff --git a/language/control-structures/throw.xml b/language/control-structures/throw.xml index 6e5bac2ea0e3..21bffad8db48 100644 --- a/language/control-structures/throw.xml +++ b/language/control-structures/throw.xml @@ -15,6 +15,10 @@ <para> Attempting to &throw; a non-<exceptionname>Throwable</exceptionname> object will throw an <exceptionname>Error</exceptionname>. + As user classes cannot implement <exceptionname>Throwable</exceptionname> + directly, the thrown object must be an instance of + <exceptionname>Error</exceptionname> or <exceptionname>Exception</exceptionname>, + or of a subclass of one of them. <example> <title>Throwing a non-<exceptionname>Throwable</exceptionname> object</title> @@ -38,8 +42,11 @@ Stack trace: <simpara> After using &throw;, the normal flow of execution is halted and the call stack is unwound until the object is caught by a &catch; block or the global scope - is reached. In the latter case, the program is terminated with - a fatal error containing the stack trace indicating where the + is reached. All &finally; blocks encountered along the way are executed. + If the global scope is reached, the object is passed to the exception handler + set with <function>set_exception_handler</function>, if one is set, and the + script terminates once the handler returns. Otherwise, the program is + terminated with a fatal error containing the stack trace indicating where the <exceptionname>Throwable</exceptionname> object was thrown. </simpara> <example> diff --git a/language/control-structures/try-catch.xml b/language/control-structures/try-catch.xml index f501e689fa55..5bb4298d0198 100644 --- a/language/control-structures/try-catch.xml +++ b/language/control-structures/try-catch.xml @@ -14,16 +14,12 @@ <simpara> When a <exceptionname>Throwable</exceptionname> error is thrown in a &try; block, PHP will attempt to find the first matching &catch; block to handle the - error. If none can be found, it will unwind the call stack until one is found or a global error handler is reached. + error. If none can be found, the call stack is unwound until a matching + &catch; block is found or the global scope is reached. + An uncaught object is then passed to the exception handler set with + <function>set_exception_handler</function>, if one is set; otherwise, + the script terminates with a fatal error. </simpara> - <note> - <simpara> - It's possible to add a handler for any uncaught - <exceptionname>Throwable</exceptionname> with - <function>set_exception_handler</function>. - This is similar to wrapping the entire code in a &try;-&catch; block. - </simpara> - </note> </sect2> <sect2 xml:id="control-structures.catch" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> <title>catch</title> @@ -40,6 +36,12 @@ object will handle the error. Normal execution resumes after the &catch; block without entering any other matching &catch; blocks. </simpara> + <note> + <simpara> + It is <emphasis>not</emphasis> recommended to catch <exceptionname>Error</exceptionname> + objects, as they signal a programming error. + </simpara> + </note> <example> <title>Catching an Exception</title> <programlisting role="php"> @@ -105,8 +107,6 @@ string(11) "MyException" <simpara> Multiple &catch; blocks can be used to handle different classes of <exceptionname>Throwable</exceptionname> errors in different ways. - Normal execution (when no error is thrown within the &try; block) will - continue after the last &catch; block defined in sequence. </simpara> <example> <title>Multiple catch blocks</title> @@ -126,7 +126,6 @@ try { <simpara> <exceptionname>Throwable</exceptionname>s can be &throw;n (or re-thrown) within a &catch; block. - If nothing is thrown, execution resumes as normal. </simpara> <example> <title>Nested Exception</title> @@ -231,5 +230,10 @@ A SpecificException was thrown, but we don't care about the details. ]]> </screen> </example> + <simpara> + See the <link linkend="language.error-handling.throwable">error handling</link> + section for the <exceptionname>Throwable</exceptionname> hierarchy and + how to define custom exceptions. + </simpara> </sect2> </sect1> diff --git a/language/error-handling.xml b/language/error-handling.xml index 96dfccb1f160..396c73e7ca6c 100644 --- a/language/error-handling.xml +++ b/language/error-handling.xml @@ -2,9 +2,6 @@ <!-- $Revision$ --> <chapter xml:id="language.error-handling" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" annotations="interactive"> <title>Error Handling</title> - <note> - <simpara>See also the <exceptionname>Exception</exceptionname> class</simpara> - </note> <simpara> Errors are a normal part of the development and life cycle of an application. As such, PHP provides multiple ways to report and deal with errors. @@ -17,7 +14,8 @@ <exceptionname>Throwable</exceptionname> errors, which are further split into <emphasis>programming</emphasis> errors via the <exceptionname>Error</exceptionname> class hierarchy and <emphasis>recoverable</emphasis> errors via the - <exceptionname>Exception</exceptionname> class hierarchy. + <exceptionname>Exception</exceptionname> class hierarchy. These errors + can be thrown with the &throw; keyword and caught with the &catch; keyword. </simpara> </listitem> <listitem> @@ -35,19 +33,16 @@ <simpara> A <exceptionname>Throwable</exceptionname> error is an execution event which disrupts the normal flow of instructions. When a <exceptionname>Throwable</exceptionname> error - is &throw;n, be that by the engine or manually, it will unwind the call stack - until it is caught by a &catch; block or the global scope is reached, in which - case the program is terminated with a fatal error. + is &throw;n, it will unwind the call stack + until it is caught by a &catch; block or the global scope is reached. All &finally; blocks it encounters along the way will be executed. + An uncaught <exceptionname>Throwable</exceptionname> error is passed to the + exception handler set with <function>set_exception_handler</function>, + if one is set; otherwise, the program is terminated with a fatal error. </simpara> <simpara> - To throw a <exceptionname>Throwable</exceptionname> error from within PHP code, one - must use the &throw; keyword followed by an instance of the - <exceptionname>Error</exceptionname> or <exceptionname>Exception</exceptionname> class or - a subclass of one of them. - Trying to throw any other object will result in an - <exceptionname>Error</exceptionname> being thrown with the following message: - <literal>Cannot throw objects that do not implement Throwable</literal>. + To throw a <exceptionname>Throwable</exceptionname> error from within PHP code, + use the &throw; keyword. </simpara> <tip> <simpara> @@ -61,22 +56,17 @@ <simpara> It is possible to handle a <exceptionname>Throwable</exceptionname> error within PHP by surrounding the code that may throw an error in a &try; block. - A &try; block must have at least one corresponding &catch; or &finally; block. </simpara> - <note> - <simpara> - It is <emphasis>not</emphasis> recommended to catch <exceptionname>Error</exceptionname> - objects, as they signal a programming error. - </simpara> - </note> <warning> <simpara> <exceptionname>Throwable</exceptionname> objects cannot be cloned. Attempting to <link linkend="language.oop5.cloning">clone</link> such an object throws an <exceptionname>Error</exceptionname> with the following message: - <literal>Trying to clone an uncloneable object of class Exception</literal>. + <literal>Trying to clone an uncloneable object of class <replaceable>ClassName</replaceable></literal>. This happens even if a subclass declares its own <link linkend="object.clone">__clone()</link> method. + See <methodname>Exception::__clone</methodname> and + <methodname>Error::__clone</methodname>. </simpara> </warning> diff --git a/language/predefined/error/clone.xml b/language/predefined/error/clone.xml index 78e90dde17cd..267c470a855a 100644 --- a/language/predefined/error/clone.xml +++ b/language/predefined/error/clone.xml @@ -12,9 +12,18 @@ <modifier>private</modifier> <type>void</type><methodname>Error::__clone</methodname> <void/> </methodsynopsis> - <para> - Error can not be cloned, so this method results in fatal error. - </para> + <simpara> + Errors do not support cloning; this method exists only to prevent it. + </simpara> + <warning> + <simpara> + Errors cannot be cloned, whether they are instances of + <exceptionname>Error</exceptionname> or of a subclass. + Attempting to <link linkend="language.oop5.cloning">clone</link> an + error throws an <exceptionname>Error</exceptionname>, which may be + caught. + </simpara> + </warning> </refsect1> <refsect1 role="parameters"> @@ -31,9 +40,11 @@ <refsect1 role="errors"> &reftitle.errors; - <para> - Errors are <emphasis>not</emphasis> clonable. - </para> + <simpara> + Attempting to clone an error throws an <exceptionname>Error</exceptionname> + with the following message: + <literal>Trying to clone an uncloneable object of class <replaceable>ClassName</replaceable></literal>. + </simpara> </refsect1> <refsect1 role="changelog"> diff --git a/language/predefined/exception/clone.xml b/language/predefined/exception/clone.xml index db137381dcf3..b525ee8a6411 100644 --- a/language/predefined/exception/clone.xml +++ b/language/predefined/exception/clone.xml @@ -40,9 +40,11 @@ <refsect1 role="errors"> &reftitle.errors; - <para> - Exceptions are <emphasis>not</emphasis> clonable. - </para> + <simpara> + Attempting to clone an exception throws an <exceptionname>Error</exceptionname> + with the following message: + <literal>Trying to clone an uncloneable object of class <replaceable>ClassName</replaceable></literal>. + </simpara> </refsect1> <refsect1 role="changelog">