[doc-en] master: Fix grammar in try catch and error handling (#5939)

Author: Kamil Tekiela (kamil-tekiela) Committer: GitHub (web-flow) Pusher: kamil-tekiela Date: 2026-10-12T23:51:50+01:00 Commit: https://github.com/php/doc-en/commit/31d9f67dd1a2574dd870a2dc2ccacbed75d2ce36 Raw diff: https://github.com/php/doc-en/commit/31d9f67dd1a2574dd870a2dc2ccacbed75d2ce36.diff Fix grammar in try catch and error handling (#5939) Changed paths: M language/control-structures/finally.xml M language/control-structures/throw.xml M language/control-structures/try-catch.xml M language/error-handling.xml Diff: diff --git a/language/control-structures/finally.xml b/language/control-structures/finally.xml index f2146d26696b..2088002f1d00 100644 --- a/language/control-structures/finally.xml +++ b/language/control-structures/finally.xml @@ -11,7 +11,7 @@ It will be executed prior to resuming the normal execution flow. The only exception to this rule is when the script is terminated abruptly, such as by a call to <function>exit</function> or by a fatal error - (for example when the maximum execution time is exceeded). + (for example, when the maximum execution time is exceeded). </simpara> <example> <title><exceptionname>Throwable</exceptionname> error handling with a &finally; block</title> @@ -25,7 +25,7 @@ function inverse($x) { try { echo inverse(5) . "\n"; } catch (\DivisionByZeroError $e) { - echo 'Caught error: ', $e->getMessage(), "\n"; + echo 'Caught error: ', $e->getMessage(), "\n"; } finally { echo "First finally.\n"; } @@ -33,7 +33,7 @@ try { try { echo inverse(0) . "\n"; } catch (\DivisionByZeroError $e) { - echo 'Caught error: ', $e->getMessage(), "\n"; + echo 'Caught error: ', $e->getMessage(), "\n"; } finally { echo "Second finally.\n"; } @@ -62,7 +62,7 @@ Hello World &catch; block. </simpara> <example> - <title>All &finally; block will be executed</title> + <title>All &finally; blocks will be executed</title> <programlisting role="php"> <![CDATA[ <?php @@ -91,7 +91,7 @@ Outer finally <title>Interaction between a &finally; block and a &return; statement</title> <simpara> One notable interaction is between the &finally; block and a &return; statement. - If a &return; statement is encountered inside either the &try; or the &catch; blocks, + If a &return; statement is encountered inside either the &try; or the &catch; block, the &finally; block will still be executed. Moreover, the &return; statement is evaluated when encountered, but the result will be returned after the &finally; block is executed. Additionally, if the &finally; block also contains a &return; statement, @@ -226,8 +226,8 @@ string(6) "Fourth" </title> <simpara> - If during the traversal of a generator a <exceptionname>Throwable</exceptionname> - error is thrown, the &finally; within the generator will be executed, + If, during the traversal of a generator, a <exceptionname>Throwable</exceptionname> + error is thrown, the &finally; block within the generator will be executed, as it is the previous element of the call stack. </simpara> <example> @@ -243,7 +243,7 @@ function generate() try { yield 1; yield 2; - } catch(\Exception $e) { + } catch (\Exception $e) { echo 'catch'; } finally { echo "finally\n"; @@ -255,7 +255,7 @@ try { echo $i, "\n"; throw new Exception(); } -} catch(Exception $e) { +} catch (Exception $e) { echo 'outer catch'; } ]]> @@ -271,15 +271,15 @@ outer catch </example> <simpara> - It is possible to &yield; within a &finally; block but if a + It is possible to &yield; within a &finally; block, but if a <exceptionname>Throwable</exceptionname> error occurs and is not caught within - the &foreach; a <literal>Cannot yield from finally in a force-closed + the &foreach;, a <literal>Cannot yield from finally in a force-closed generator</literal> <exceptionname>Error</exceptionname> is thrown. </simpara> <example> <title> - Error when &yield;ing in &finally; block when an <exceptionname>Exception</exceptionname> - has been thrown + Error when &yield;ing in a &finally; block when an + <exceptionname>Exception</exceptionname> has been thrown </title> <programlisting role="php"> <![CDATA[ @@ -289,7 +289,7 @@ function generate() try { yield 1; yield 2; - } catch(\Exception $e) { + } catch (\Exception $e) { echo 'catch'; } finally { echo "finally\n"; @@ -302,7 +302,7 @@ try { echo $i, "\n"; throw new Exception(); } -} catch(Exception $e) { +} catch (Exception $e) { echo 'outer catch'; } ]]> @@ -330,11 +330,11 @@ Stack trace: <sect2> <title>Interaction between a &finally; block and a call to <function>exit</function></title> <simpara> - When <function>exit</function> is called within a &try; or a &catch; block + When <function>exit</function> is called within a &try; or a &catch; block, all &finally; blocks are skipped. </simpara> <example> - <title>Interaction between &finally; block and <function>exit</function> called in &try; block</title> + <title>Interaction between a &finally; block and <function>exit</function> called in a &try; block</title> <programlisting role="php"> <![CDATA[ <?php @@ -354,7 +354,7 @@ quit </screen> </example> <example> - <title>Interaction between &finally; block and <function>exit</function> called in &catch; block</title> + <title>Interaction between a &finally; block and <function>exit</function> called in a &catch; block</title> <programlisting role="php"> <![CDATA[ <?php @@ -402,10 +402,10 @@ quit <simpara> When <function>exit</function> is called within a &finally; block, - all other outer &finally; blocks are skipped. + all outer &finally; blocks are skipped. </simpara> <example> - <title>Skipping outer &finally; block by calling <function>exit</function></title> + <title>Skipping an outer &finally; block by calling <function>exit</function></title> <programlisting role="php"> <![CDATA[ <?php @@ -434,7 +434,7 @@ inner finally <title>Edge case of calling <function>exit</function> in a &foreach; over a generator</title> <simpara> This one edge case behaviour is highly dependent on which version of PHP - the code is executed. + the code is executed with. </simpara> <informalexample> @@ -446,7 +446,7 @@ function generate() try { yield 1; yield 2; - } catch(\Exception $e) { + } catch (\Exception $e) { echo 'catch'; } finally { echo "inner finally\n"; diff --git a/language/control-structures/throw.xml b/language/control-structures/throw.xml index 9bd0b2f993a1..6e5bac2ea0e3 100644 --- a/language/control-structures/throw.xml +++ b/language/control-structures/throw.xml @@ -5,12 +5,11 @@ <?phpdoc print-version-for="throw"?> <simpara> The &throw; keyword is an expression and may be used in any expression context. - It takes an instance of a <exceptionname>Throwable</exceptionname> object as an - argument. + It takes a <exceptionname>Throwable</exceptionname> object as an argument. </simpara> <caution> <simpara> - Prior to PHP 8.0, the &throw; keyword was a statement and not an expression. + Prior to PHP 8.0.0, the &throw; keyword was a statement and not an expression. </simpara> </caution> <para> @@ -37,11 +36,11 @@ Stack trace: </para> <simpara> - After using &throw; the normal flow of execution is halted and the call stack + 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 - <exceptionname>Throwable</exceptionname> object has been thrown. + <exceptionname>Throwable</exceptionname> object was thrown. </simpara> <example> <title>Throwing an Exception in the global scope</title> @@ -93,7 +92,7 @@ Stack trace: </example> <simpara> - As &throw; is an expression it can be used to branch out on the result + As &throw; is an expression, it can be used to branch out on the result of another expression if its value is inappropriate. </simpara> <example> diff --git a/language/control-structures/try-catch.xml b/language/control-structures/try-catch.xml index c372bf09061d..f501e689fa55 100644 --- a/language/control-structures/try-catch.xml +++ b/language/control-structures/try-catch.xml @@ -1,7 +1,7 @@ <?xml version="1.0" encoding="utf-8"?> <!-- $Revision$ --> <sect1 xml:id="control-structures.try-catch" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> - <title>Try...Catch</title> + <title>try...catch</title> <sect2 xml:id="control-structures.try" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> <title>try</title> <?phpdoc print-version-for="try"?> @@ -12,7 +12,7 @@ &catch; or &finally; block. </simpara> <simpara> - When a <exceptionname>Throwable</exceptionname> error is thrown in a &try; block + 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. </simpara> @@ -32,7 +32,7 @@ A &catch; block defines how to respond to a thrown <exceptionname>Throwable</exceptionname> error. It specifies one or more subclasses of <exceptionname>Throwable</exceptionname> (most commonly <exceptionname>Exception</exceptionname>) it can handle, and - optionally a variable to which to assign the exception. + optionally a variable to which the exception is assigned. </simpara> <simpara> The first &catch; block @@ -67,8 +67,8 @@ Hello World <simpara> As of PHP 7.1.0, a &catch; block may specify a union of <exceptionname>Throwable</exceptionname> subclasses that the block should handle - using the pipe (<literal>|</literal>) character. This is useful for when - different exceptions from different class hierarchies are handled the same. + using the pipe (<literal>|</literal>) character. This is useful when + different exceptions from different class hierarchies are handled in the same way. </simpara> <example> <title>Catching a union of classes to handle</title> @@ -106,7 +106,7 @@ string(11) "MyException" 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 that last &catch; block defined in sequence. + continue after the last &catch; block defined in sequence. </simpara> <example> <title>Multiple catch blocks</title> @@ -126,7 +126,7 @@ try { <simpara> <exceptionname>Throwable</exceptionname>s can be &throw;n (or re-thrown) within a &catch; block. - If nothing is thrown, the execution resumes as normal. + If nothing is thrown, execution resumes as normal. </simpara> <example> <title>Nested Exception</title> @@ -164,7 +164,7 @@ string(4) "foo!" </example> <caution> <simpara> - Throwing an object inside a &catch; block will <emphasis>not</emphasis> + An object thrown inside a &catch; block will <emphasis>not</emphasis> be caught by an adjacent &catch; block. </simpara> <example> @@ -178,9 +178,9 @@ class B extends Exception {} try { throw new A; -} catch(A $e) { +} catch (A $e) { throw new B; -} catch(B) { +} catch (B) { echo 'Hello'; } diff --git a/language/error-handling.xml b/language/error-handling.xml index 2ff1549d27d3..96dfccb1f160 100644 --- a/language/error-handling.xml +++ b/language/error-handling.xml @@ -7,7 +7,7 @@ </note> <simpara> Errors are a normal part of the development and life cycle of an application. - As such PHP provides multiple ways to inform and deal with errors. + As such, PHP provides multiple ways to report and deal with errors. </simpara> <para> PHP has two main mechanisms for reporting errors: @@ -22,7 +22,7 @@ </listitem> <listitem> <simpara> - Diagnostic errors which are classified into different + Diagnostic errors, which are classified into different <link linkend="errorfunc.constants">severities</link>. </simpara> </listitem> @@ -45,7 +45,7 @@ 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 an object that is not will result in an + 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>. </simpara> @@ -53,35 +53,35 @@ <simpara> The <link linkend="intro.spl">Standard PHP Library (SPL)</link> provides various <link linkend="spl.exceptions">built-in exceptions</link>. - And it's possible to create custom exceptions by + It is also possible to create custom exceptions by <link linkend="language.error-handling.throwable.extending">extending the Exception class</link>. </simpara> </tip> <simpara> It is possible to handle a <exceptionname>Throwable</exceptionname> error within PHP - by surrounding the code susceptible to throw an error in a &try; block. + 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 those signal a programming error. + 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>, even if a subclass declares - its own <link linkend="object.clone">__clone()</link> method, with - the following message: + object throws an <exceptionname>Error</exceptionname> with the following message: <literal>Trying to clone an uncloneable object of class Exception</literal>. + This happens even if a subclass declares its own + <link linkend="object.clone">__clone()</link> method. </simpara> </warning> <sect2 xml:id="language.error-handling.throwable.user"> - <title><literal>Global exception handler</literal></title> + <title>Global exception handler</title> <simpara> It's possible to add a handler for any uncaught <exceptionname>Throwable</exceptionname> with @@ -93,20 +93,18 @@ </sect2> <sect2 xml:id="language.error-handling.throwable.extending"> - <title>Extending Exceptions</title> + <title>Extending exceptions</title> <simpara> A user-defined exception can be defined by extending the built-in <exceptionname>Exception</exceptionname> class. - To see which methods and properties are accessible within a child class - derived from <exceptionname>Exception</exceptionname> visit its page. </simpara> <simpara> If a class extends the built-in <exceptionname>Exception</exceptionname> class and - re-defines the <link linkend="language.oop5.decon">constructor</link>, + redefines the <link linkend="language.oop5.decon">constructor</link>, it is highly recommended that it also call <code>parent::__construct()</code> to ensure all available data has been properly assigned. The <link linkend="object.tostring">__toString()</link> method can be overridden - to provide a custom output when the object is used as a string. + to provide custom output when the object is used as a string. </simpara> <example> <title>Extending <exceptionname>Exception</exceptionname></title> @@ -220,7 +218,7 @@ A custom function for this type of exception <simpara> Diagnostic errors, also known as traditional errors, are used to signal a number of different conditions, and can be displayed and/or logged as required. - By default PHP will report all diagnostic errors. (Prior to PHP 8.0, + By default, PHP will report all diagnostic errors. (Prior to PHP 8.0.0, <constant>E_NOTICE</constant> and <constant>E_DEPRECATED</constant> diagnostics were not reported by default.) </simpara> @@ -240,10 +238,10 @@ A custom function for this type of exception <simpara> In a development environment, <link linkend="ini.error-reporting"><parameter>error_reporting</parameter></link> - should always be set to <constant>E_ALL</constant> to be aware of and fix - issues raised by PHP. - However, in production the level of verbosity could be reduced to - <code>E_ALL &amp; ~E_NOTICE &amp; ~E_DEPRECATED</code>, but in many cases + should always be set to <constant>E_ALL</constant> so that issues raised + by PHP are noticed and fixed. + In production, the level of verbosity can be reduced to + <code>E_ALL &amp; ~E_NOTICE &amp; ~E_DEPRECATED</code>, although in many cases <constant>E_ALL</constant> is still appropriate, as it may provide early warning of potential issues. </simpara> @@ -253,7 +251,7 @@ A custom function for this type of exception What happens to the diagnostics depends on two further &php.ini; directives. <link linkend="ini.display-errors"><parameter>display_errors</parameter></link> controls whether the diagnostic is shown as part of the script's output. - This should always be disabled in a production environment, as it can include + This should always be disabled in a production environment, as the output can include confidential information such as database passwords, but is often useful to enable in development, as it ensures immediate reporting of issues. </simpara> @@ -265,7 +263,7 @@ A custom function for this type of exception defined by <link linkend="ini.error-log"><parameter>error_log</parameter></link>. This can be extremely useful in a production environment, as diagnostics are - logged when they occur and can then generate reports based on those logs. + logged when they occur, and reports can then be generated from those logs. </simpara> <simpara> Individual diagnostics can be suppressed using the @@ -274,20 +272,20 @@ A custom function for this type of exception <warning> <simpara> - Prior to PHP 8.0.0 it was possible to suppress critical diagnostics that + Prior to PHP 8.0.0, it was possible to suppress critical diagnostics that would terminate the execution of the PHP script. </simpara> </warning> <note> <simpara> - Diagnostics can be added, removed, have their severity altered or be - elevated to a <exceptionname>Throwable</exceptionname> error in between PHP versions. + Between PHP versions, diagnostics may be added or removed, have their + severity changed, or be elevated to <exceptionname>Throwable</exceptionname> errors. </simpara> </note> <sect2 xml:id="language.error-handling.diagnostic.user"> - <title>User defined diagnostic handler</title> + <title>User-defined diagnostic handler</title> <simpara> If PHP's default diagnostic handling is inadequate, @@ -296,9 +294,9 @@ A custom function for this type of exception Some diagnostics, such as <constant>E_ERROR</constant> and <constant>E_PARSE</constant>, cannot be handled this way (see <function>set_error_handler</function> for the full list). - The others can be handled in various ways. For example, this can be used to show a custom - error page to the user and then report more directly than via a log, such - as by sending an e-mail. + The others can be handled in various ways. For example, a custom handler can + show an error page to the user and report the error more directly than a log + would, such as by sending an email. </simpara> <simpara> @@ -312,7 +310,7 @@ A custom function for this type of exception <?php function exceptions_error_handler($severity, $message, $filename, $lineno) { if (error_reporting() & $severity) { - throw new ErrorException($message, 0, $severity, $filename, $lineno); + throw new ErrorException($message, 0, $severity, $filename, $lineno); } } @@ -322,7 +320,7 @@ set_error_handler('exceptions_error_handler'); <note> <simpara> It is important to verify that the severity is included in the current - list of reportable diagnostics, otherwise the + list of reportable diagnostics; otherwise, the <literal linkend="language.operators.errorcontrol">@</literal> operator will be broken, as an exception will be thrown for a suppressed diagnostic. <!-- TODO: add an example? -->