com doc/zh: 补完 Exceptions: language/excep tions.xml

[email protected] (Dai Jie) Sun, 10 Jan 2021 16:41:01 +0000
Newsgroups php.doc.zh
Message-ID <[email protected]>
Commit:    47828aab75c5d95a2e0cd3c0db6906084026b4e9
Author:    戴劼 <[email protected]>         Mon, 11 Jan 2021 00:41:01 +0800
Parents:   39d430008a10723b1a26d61b5c7165911e1331f8
Branches:  master

Link:       http://git.php.net/?p=doc/zh.git;a=commitdiff;h=47828aab75c5d95a2e0cd3c0db6906084026b4e9

Log:
补完 Exceptions

Changed paths:
  M  language/exceptions.xml
diff_47828aab75c5d95a2e0cd3c0db6906084026b4e9.txt (text/plain, 13.6 KB)
diff --git a/language/exceptions.xml b/language/exceptions.xml
index aab4d391..7aa1da9e 100644
--- a/language/exceptions.xml
+++ b/language/exceptions.xml
@@ -1,15 +1,15 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 351652 Maintainer: daijie Status: ready -->
+<!-- EN-Revision: 1d58f726462a821d3f926fb61247357f49fa1ce5 Maintainer: daijie Status: ready -->
 
  <chapter xml:id="language.exceptions" xmlns="http://docbook.org/ns/docbook">
-  <title>异常处理</title>
+  <title>异常</title>
    
   <sect1 xml:id="language.exceptions.extending">
    <title>扩展(extend) 异常处理类</title>
    <para>
     用户可以用自定义的异常处理类来扩展 PHP
-    内置的异常处理类。以下的代码说明了在内置的异常处理类中,哪些属性和方法在子类中是可访问和可继承的。译者注:以下这段代码只为说明内置异常处理类的结构,它并不是一段有实际意义的可用代码。
+    内置的异常处理类。以下的代码说明了在内置的异常处理类中,哪些属性和方法在子类中是可访问和可继承的。
    </para>
    <example>
     <title>内置的异常处理类</title>
@@ -19,27 +19,27 @@
 class Exception extends Throwable
 {
     protected $message = 'Unknown exception';   // 异常信息
-    private   $string;                          // __toString cache
-    protected $code = 0;                        // 用户自定义异常代码
-    protected $file;                            // 发生异常的文件名
-    protected $line;                            // 发生异常的代码行号
+    private   $string;                          // __toString 的缓存
+    protected $code = 0;                        // 用户自定义异常错误码
+    protected $file;                            // 发生异常的源文件名
+    protected $line;                            // 发生异常的源代码行号
     private   $trace;                           // backtrace
-    private   $previous;                        // previous exception if nested exception
+    private   $previous;                        // 如果是嵌套异常,则是之前的 exception
 
     public function __construct($message = null, $code = 0, Exception $previous = null);
 
     final private function __clone();           // Inhibits cloning of exceptions.
 
-    final public  function getMessage();        // 返回异常信息
-    final public  function getCode();           // 返回异常代码
-    final public  function getFile();           // 返回发生异常的文件名
-    final public  function getLine();           // 返回发生异常的代码行号
+    final public  function getMessage();        // 异常信息
+    final public  function getCode();           // 异常错误码
+    final public  function getFile();           // 发生异常的源文件名
+    final public  function getLine();           // 发生异常的源代码行号
     final public  function getTrace();          // backtrace() 数组
     final public  function getPrevious();       // 之前的 exception
     final public  function getTraceAsString();  // 已格成化成字符串的 getTrace() 信息
 
     // Overrideable
-    public function __toString();               // 可输出的字符串
+    public function __toString();               // 可输出的格式化后的字符串
 }
 ?>
 ]]>
@@ -70,13 +70,13 @@ class MyException extends Exception
 {
     // 重定义构造器使 message 变为必须被指定的属性
     public function __construct($message, $code = 0, Exception $previous = null) {
-        // 自定义的代码
+        // 这里写用户的代码
 
         // 确保所有变量都被正确赋值
         parent::__construct($message, $code, $previous);
     }
 
-    // 自定义字符串输出的样式
+    // 自定义字符串输出的格式
     public function __toString() {
         return __CLASS__ . ": [{$this->code}]: {$this->message}\n";
     }
@@ -88,7 +88,7 @@ class MyException extends Exception
 
 
 /**
- * 创建一个用于测试异常处理机制的类
+ * 创建一个类,测试该 exception 类
  */
 class TestException
 {
@@ -130,7 +130,7 @@ try {
     echo "Caught Default Exception\n", $e;
 }
 
-// Continue execution
+// 继续执行后续代码
 var_dump($o); // Null
 echo "\n\n";
 
@@ -208,66 +208,56 @@ echo "\n\n";
   <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.
+    &catch; 定义了处理抛出异常的方式。
+    &catch; 块定义了它能处理的异常/错误的类型,并可以选择将异常赋值到变量中。
+    (在 PHP 8.0.0 之前的版本中必须要赋值到变量)
+    如果遇到抛出对象的类型匹配了首个 &catch; 块的异常或错误,将会处理该对象。
    </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.
+    可用多个 &catch; 捕获不同的异常类。
+    正常情况下(&try; 代码块里没有抛出异常)会在最后一个定义的 &catch; 后面继续执行。
+    &catch; 代码块里也可以 &throw; 或者重新抛出异常。
+    不抛出的话,会在触发的 &catch; 后面继续执行。
    </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>.
+    当 PHP 抛出一个异常时,将不会执行后续的代码语句,并会尝试查找首个匹配的 &catch; 代码块。
+    如果没有用 <function>set_exception_handler</function> 设置异常处理函数,
+    PHP 会在异常未被捕获时产生 Fatal 级错误,提示 "<literal>Uncaught Exception ...</literal>"
+    消息。
    </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.
+    从 PHP 7.1.0 起 &catch; 可以用竖线符(<literal>|</literal>) 指定多个异常。
+    如果在不同的类层次结构中,不同异常的异常需要用同样的方式处理,就特别适用这种方式。
    </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.
+    从 PHP 8.0.0 起,捕获的异常不再强制要求指定变量名。
+    &catch; 代码块会在未指定时继续执行,只是无法访问到抛出的对象。
    </para>
   </simplesect>
 
   <simplesect xml:id="language.exceptions.finally">
    <title><literal>finally</literal></title>
    <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.
+    &finally; 代码块可以放在 &catch; 之后,或者直接代替它。 
+    无论是否抛出了异常,在 &try; 和 &catch; 之后、在执行后续代码之前,
+    放在 &finally; 里的代码总是会执行。
    </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.
+    值得注意的是 &finally; 和 &return; 语句之间存在相互影响。
+    如果在 &try; 或 &catch; 里遇到 &return;,仍然会执行 &finally; 里的代码。
+    而且,遇到 &return; 语句时,会先执行 &finally; 再返回结果。
+    此外,如果 &finally; 里也包含了 &return; 语句,将返回 &finally; 里的值。
    </para>
   </simplesect>
 
  <simplesect xml:id="language.exceptions.exception-handler">
-  <title><literal>Global exception handler</literal></title>
+  <title><literal>全局异常处理器</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;.
+   当允许异常冒泡到全局范围时,它可以被全局异常处理器捕获到。
+   <function>set_exception_handler</function> 
+   可以设置一个函数,在没有调用其他块时代替 &catch;。
+   在本质上,实现的效果等同于整个程序被 &try;-&catch; 包裹起来,
+   而该函数就是 &catch;。
   </para>
  </simplesect>
 
@@ -276,15 +266,14 @@ echo "\n\n";
 
    <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 easily translated to
-     exceptions with <link linkend="class.errorexception">ErrorException</link>.
-     This technique only works with non-fatal errors, however.
+     PHP 内部函数主要使用 <link linkend="ini.error-reporting">错误报告</link>,
+     只有一些现代 <link linkend="language.oop5">面向对象</link> 的扩展使用异常。
+     不过,错误很容易用 <link linkend="class.errorexception">ErrorException</link>
+     转化成异常。
+     然而,这个技术方案仅适用非 Fatal 级的错误。
     </para>
     <example>
-     <title>Converting error reporting to exceptions</title>
+     <title>将错误报告转成异常</title>
      <programlisting role="php">
 <![CDATA[
 <?php
@@ -300,9 +289,8 @@ set_error_handler('exceptions_error_handler');
    </note>
    <tip>
     <para>
-     The <link linkend="intro.spl">Standard PHP Library (SPL)</link> provides
-     a good number of <link linkend="spl.exceptions">built-in
-     exceptions</link>.
+     <link linkend="intro.spl">PHP 标准库(SPL)</link> 
+     提供了大量的 <link linkend="spl.exceptions">标准内置异常</link>。
     </para>
    </tip>
   </simplesect>
@@ -311,7 +299,7 @@ set_error_handler('exceptions_error_handler');
    &reftitle.examples;
 
    <example>
-    <title>Throwing an Exception</title>
+    <title>抛出一个异常</title>
     <programlisting role="php">
 <![CDATA[
 <?php
@@ -344,7 +332,7 @@ Hello World
     </screen>
    </example>
    <example>
-    <title>Exception handling with a &finally; block</title>
+    <title>带 &finally; 块的异常处理</title>
     <programlisting role="php">
 <![CDATA[
 <?php
@@ -371,7 +359,7 @@ try {
     echo "Second finally.\n";
 }
 
-// Continue execution
+// 继续执行
 echo "Hello World\n";
 ?>
 ]]>
@@ -388,7 +376,7 @@ Hello World
     </screen>
    </example>
    <example>
-    <title>Interaction between the &finally; block and &return;</title>
+    <title>&finally; 块和 &return; 之间的用法</title>
     <programlisting role="php">
 <![CDATA[
 <?php
@@ -415,7 +403,7 @@ finally
     </screen>
    </example>
    <example>
-    <title>Nested Exception</title>
+    <title>异常嵌套</title>
     <programlisting role="php">
 <![CDATA[
 <?php
@@ -428,7 +416,7 @@ class Test {
             try {
                 throw new MyException('foo!');
             } catch (MyException $e) {
-                // rethrow it
+                // 重新 throw
                 throw $e;
             }
         } catch (Exception $e) {
@@ -451,7 +439,7 @@ string(4) "foo!"
     </screen>
    </example>
    <example>
-    <title>Multi catch exception handling</title>
+    <title>多个异常的捕获处理</title>
     <programlisting role="php">
 <![CDATA[
 <?php
@@ -484,8 +472,8 @@ string(11) "MyException"
     </screen>
    </example>
    <example>
-    <title>Omitting the caught variable</title>
-    <para>Only permitted in PHP 8.0.0 and later.</para>
+    <title>忽略捕获的变量</title>
+    <para>仅仅在 PHP 8.0.0 及以上版本有效</para>
     <programlisting role="php">
 <![CDATA[
 <?php
@@ -506,8 +494,8 @@ try {
     </programlisting>
    </example>
    <example>
-    <title>Throw as an expression</title>
-    <para>Only permitted in PHP 8.0.0 and later.</para>
+    <title>以表达式的形式抛出</title>
+    <para>仅仅在 PHP 8.0.0 及以上版本有效</para>
     <programlisting role="php">
 <![CDATA[
 <?php