[WIP] Refactor error pages

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

appendices/migration70/incompatible/error-handling.xml

@@ -19,7 +19,7 @@
 
  <para>
   A fuller description of how errors operate in PHP 7 can be found
-  <link linkend="language.errors.php7">on the PHP 7 errors page</link>. This
+  <link linkend="language.error-handling.throwable">on the PHP 7 errors page</link>. This
   migration guide will merely enumerate the changes that affect backward
   compatibility.
  </para>

language/control-structures.xml

@@ -53,6 +53,9 @@
  &language.control-structures.require-once;
  &language.control-structures.include-once;
  &language.control-structures.goto;
+ <!-- &language.control-structures.throw; -->
+ &language.control-structures.try-catch;
+ &language.control-structures.finally;
 
 </chapter>
 

language/control-structures/finally.xml

@@ -0,0 +1,90 @@
+<?xml version="1.0" encoding="utf-8"?>
+<sect1 xml:id="control-structures.finally" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <title>else</title>
+ <?phpdoc print-version-for="finally"?>
+ <para>
+  A &finally; block may also be specified after or
+  instead of &catch; blocks. Code within the &finally; block will always be
+  executed after the &try; and &catch; blocks, regardless of whether an
+  exception has been thrown, and before normal execution resumes.
+ </para>
+ <para>
+  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,
+  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,
+  the value from the &finally; block is returned.
+ </para>
+ <example>
+  <title>Exception handling with a &finally; block</title>
+  <programlisting role="php">
+   <![CDATA[
+<?php
+function inverse($x) {
+    if (!$x) {
+        throw new Exception('Division by zero.');
+    }
+    return 1/$x;
+}
+
+try {
+    echo inverse(5) . "\n";
+} catch (Exception $e) {
+    echo 'Caught exception: ',  $e->getMessage(), "\n";
+} finally {
+    echo "First finally.\n";
+}
+
+try {
+    echo inverse(0) . "\n";
+} catch (Exception $e) {
+    echo 'Caught exception: ',  $e->getMessage(), "\n";
+} finally {
+    echo "Second finally.\n";
+}
+
+// Continue execution
+echo "Hello World\n";
+?>
+]]>
+  </programlisting>
+  &example.outputs;
+  <screen>
+   <![CDATA[
+0.2
+First finally.
+Caught exception: Division by zero.
+Second finally.
+Hello World
+]]>
+  </screen>
+ </example>
+ <example>
+  <title>Interaction between the &finally; block and &return;</title>
+  <programlisting role="php">
+   <![CDATA[
+<?php
+
+function test() {
+    try {
+        throw new Exception('foo');
+    } catch (Exception $e) {
+        return 'catch';
+    } finally {
+        return 'finally';
+    }
+}
+
+echo test();
+?>
+]]>
+  </programlisting>
+  &example.outputs;
+  <screen>
+   <![CDATA[
+finally
+]]>
+  </screen>
+ </example>
+</sect1>

language/control-structures/try-catch.xml

@@ -0,0 +1,104 @@
+<?xml version="1.0" encoding="utf-8"?>
+<sect1 xml:id="control-structures.try-catch" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <title>try-catch blocks</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"?>
+  <para>
+   W.I.P. Description for try.
+  </para>
+ </sect2>
+ <sect2 xml:id="control-structures.catch" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+  <title>catch</title>
+  <?phpdoc print-version-for="catch"?>
+  <!-- W.I.P. Improve -->
+  <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. 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
+   executed, and PHP will attempt to find the first matching &catch; block.
+   If an exception is not caught, a PHP Fatal Error will be issued with an
+   "<literal>Uncaught Exception ...</literal>" message, unless a handler has
+   been defined with <function>set_exception_handler</function>.
+  </para>
+  <para>
+   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>
+  <example>
+   <title>Multi catch exception handling</title>
+   <programlisting role="php">
+    <![CDATA[
+<?php
+
+class MyException extends Exception { }
+
+class MyOtherException extends Exception { }
+
+class Test {
+    public function testing() {
+        try {
+            throw new MyException();
+        } catch (MyException | MyOtherException $e) {
+            var_dump(get_class($e));
+        }
+    }
+}
+
+$foo = new Test;
+$foo->testing();
+
+?>
+]]>
+   </programlisting>
+   &example.outputs;
+   <screen>
+    <![CDATA[
+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>
+ </sect2>
+</sect1>