Exception updates

* Empty catch statements
* Throw as an expression
* Various other cleanup while I was there to remove comments

I also deleted a crapload of comments. It's so satisfying.

Closes GH-238.


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@351652 c90b9560-bf6c-de11-be94-00142212c4b1

language/exceptions.xml

@@ -188,22 +188,43 @@ echo "\n\n";
     of potential exceptions. Each &try; must have at least one corresponding
     &catch; or &finally; block.
    </para>
-
+   <para>
+    If an exception is thrown and its current function scope has no &catch;
+    block, the exception will "bubble up" the call stack to the calling
+    function until it finds a matching &catch; block.  All &finally; blocks it encounters
+    along the way will be executed. If the call stack is unwound all the way to the
+    global scope without encountering a matching &catch; block, the program will
+    terminate with a fatal error unless a global exception handler has been set.
+   </para>
    <para>
     The thrown object must be an instance of the
     <classname>Exception</classname> class or a subclass of
     <classname>Exception</classname>. Trying to throw an object that is not
     will result in a PHP Fatal Error.
    </para>
+   <para>
+    As of PHP 8.0.0, the &throw; keyword is an expression and may be used in any expression
+    context. In prior versions it was a statement and was required to be on its own line.
+   </para>
+
   </simplesect>
 
   <simplesect xml:id="language.exceptions.catch">
    <title><literal>catch</literal></title>
+   <para>
+    A &catch; block defines how to respond to a thrown exception.  A &catch;
+    block defines one or more types of exception or error it can handle, and
+    optionally a variable to which to assign the exception. (The variable was
+    required prior to PHP 8.0.0.)  The first &catch; block a thrown exception
+    or error encounters that matches the type of the thrown object will handle
+    the object.
+   </para>
    <para>
     Multiple &catch; blocks can be used to catch different classes of
     exceptions. Normal execution (when no exception is thrown within the &try;
     block) will continue after that last &catch; block defined in sequence.
-    Exceptions can be &throw;n (or re-thrown) within a &catch; block.
+    Exceptions can be &throw;n (or re-thrown) within a &catch; block. If not,
+    execution will continue after the &catch; block that was triggered.
    </para>
    <para>
     When an exception is thrown, code following the statement will not be
@@ -213,11 +234,16 @@ echo "\n\n";
     been defined with <function>set_exception_handler</function>.
    </para>
    <para>
-    In PHP 7.1 and later, a &catch; block may specify multiple exceptions
+    As of PHP 7.1.0, a &catch; block may specify multiple exceptions
     using the pipe (<literal>|</literal>) character. This is useful for when
     different exceptions from different class hierarchies are handled the
     same.
    </para>
+   <para>
+    As of PHP 8.0.0, the variable name for a caught exception is optional.
+    If not specified, the &catch; block will still execute but will not
+    have access to the thrown object.
+   </para>
   </simplesect>
 
   <simplesect xml:id="language.exceptions.finally">
@@ -238,17 +264,43 @@ echo "\n\n";
    </para>
   </simplesect>
 
-  <simplesect xml:id="language.exceptions.notes">
+ <simplesect xml:id="language.exceptions.exception-handler">
+  <title><literal>Global exception handler</literal></title>
+  <para>
+   If an exception is allowed to bubble up to the global scope, it may be caught
+   by a global exception handler if set.  The <function>set_exception_handler</function>
+   function can set a function that will be called in place of a &catch; block if no
+   other block is invoked.  The effect is essentially the same as if the entire program
+   were wrapped in a &try;-&catch; block with that function as the &catch;.
+  </para>
+ </simplesect>
+
+ <simplesect xml:id="language.exceptions.notes">
    &reftitle.notes;
 
    <note>
     <para>
      Internal PHP functions mainly use
      <link linkend="ini.error-reporting">Error reporting</link>, only modern
      <link linkend="language.oop5">Object oriented</link>
-     extensions use exceptions. However, errors can be simply translated to
+     extensions use exceptions. However, errors can be easily translated to
      exceptions with <link linkend="class.errorexception">ErrorException</link>.
+     This technique only works with non-fatal errors, however.
     </para>
+    <example>
+     <title>Converting error reporting to exceptions</title>
+     <programlisting role="php">
+<![CDATA[
+<?php
+function exceptions_error_handler($severity, $message, $filename, $lineno) {
+    throw new ErrorException($message, 0, $severity, $filename, $lineno);
+}
+
+set_error_handler('exceptions_error_handler');
+?>
+]]>
+     </programlisting>
+    </example>
    </note>
    <tip>
     <para>
@@ -435,6 +487,50 @@ string(11) "MyException"
 ]]>
     </screen>
    </example>
+   <example>
+    <title>Omitting the caught variable</title>
+    <para>Only permitted in PHP 8.0.0 and later.</para>
+    <programlisting role="php">
+<![CDATA[
+<?php
+
+class SpecificException extends Exception {}
+
+function test() {
+    throw new SpecificException('Oopsie');
+}
+
+try {
+    test();
+} catch (SpecificException) {
+    print "A SpecificException was thrown, but we don't care about the details.";
+}
+?>
+]]>
+    </programlisting>
+   </example>
+   <example>
+    <title>Throw as an expression</title>
+    <para>Only permitted in PHP 8.0.0 and later.</para>
+    <programlisting role="php">
+<![CDATA[
+<?php
+
+class SpecificException extends Exception {}
+
+function test() {
+    do_something_risky() or throw new Exception('It did not work');
+}
+
+try {
+    test();
+} catch (Exception $e) {
+    print $e->getMessage();
+}
+?>
+]]>
+    </programlisting>
+   </example>
   </simplesect>
 
  </chapter>