Update language

php · Oct 24, 2023 · 0f214a0 · 0f214a0
1 parent 2197489
commit 0f214a0
Show file tree

Hide file tree

Showing 7 changed files with 134 additions and 62 deletions.
diff --git a/language/errors.xml b/language/errors.xml
@@ -1,12 +1,11 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: f0fe52e5a693be46f0c81012b15b929ad264228e Maintainer: ErnestToo Status: ready -->
-<!-- Reviewed: no -->
-
-<chapter xml:id="language.errors" xmlns="http://docbook.org/ns/docbook" xmlns:phd="http://www.php.net/ns/phd">
+<!-- EN-Revision: 7a75b854c8c52226d38397e7e8177e339fdb273f Maintainer: ErnestToo Status: ready -->
+<!-- CREDITS: mowangjuanzi -->
+<chapter xml:id="language.errors" xmlns="http://docbook.org/ns/docbook">
  <title>错误</title>
 
- <sect1 phd:chunk="false" xml:id="language.errors.intro">
+ <sect1 annotations="chunk:false" xml:id="language.errors.intro">
   <title>介绍</title>
 
   <para>

diff --git a/language/exceptions.xml b/language/exceptions.xml
@@ -1,10 +1,8 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 6f9e433f4b4a591801c3a49fc459550ea1b5f613 Maintainer: daijie Status: ready -->
+<!-- EN-Revision: 7a75b854c8c52226d38397e7e8177e339fdb273f Maintainer: daijie Status: ready -->
 <!-- CREDITS: mowangjuanzi -->
-<chapter xml:id="language.exceptions" xmlns:phd="http://www.php.net/ns/phd">
- <!-- we use our own DTD instead of xmlns="http://docbook.org/ns/docbook" so that we can use
- <sect1 phd:chunk="false"> -->
+<chapter xml:id="language.exceptions" xmlns="http://docbook.org/ns/docbook">
  <title>异常</title>
  <para>
   PHP 有一个和其他语言相似的异常模型。在 PHP 里可以 &throw; 并捕获（&catch;）异常。为了捕获潜在的异常，代码会包含在
@@ -21,7 +19,7 @@
   PHP 8.0.0 起，&throw; 关键词现在开始是表达式，可用于任何表达式上下文。在此之前，它是语句，必须独占一行。
  </para>
 
-  <sect1 phd:chunk="false" xml:id="language.exceptions.catch">
+  <sect1 annotations="chunk:false" xml:id="language.exceptions.catch">
    <title><literal>catch</literal></title>
    <para>
     &catch; 定义了处理抛出异常的方式。
@@ -51,7 +49,7 @@
    </para>
   </sect1>
 
-  <sect1 phd:chunk="false" xml:id="language.exceptions.finally">
+  <sect1 annotations="chunk:false" xml:id="language.exceptions.finally">
    <title><literal>finally</literal></title>
    <para>
     &finally; 代码块可以放在 &catch; 之后，或者直接代替它。 
@@ -66,7 +64,7 @@
    </para>
   </sect1>
 
- <sect1 phd:chunk="false" xml:id="language.exceptions.exception-handler">
+ <sect1 annotations="chunk:false" xml:id="language.exceptions.exception-handler">
   <title>全局异常处理程序</title>
   <para>
    当允许异常冒泡到全局作用域时，它可以被全局异常处理器捕获到。
@@ -77,7 +75,7 @@
   </para>
  </sect1>
 
- <sect1 phd:chunk="false" xml:id="language.exceptions.notes">
+ <sect1 annotations="chunk:false" xml:id="language.exceptions.notes">
    &reftitle.notes;
 
    <note>
@@ -111,7 +109,7 @@ set_error_handler('exceptions_error_handler');
    </tip>
  </sect1>
 
-  <sect1 phd:chunk="false" xml:id="language.exceptions.examples">
+  <sect1 annotations="chunk:false" xml:id="language.exceptions.examples">
    &reftitle.examples;
 
    <example>

diff --git a/language/oop5/decon.xml b/language/oop5/decon.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 0cb9fcef71ebcd6844364e09591ed765d84194fc Maintainer: lm92 Status: ready -->
+<!-- EN-Revision: 7b50ce5861a2fcceaa05da7adb3d946a025ca72d Maintainer: lm92 Status: ready -->
 <!-- CREDITS: mowangjuanzi -->
 <sect1 xml:id="language.oop5.decon" xmlns="http://docbook.org/ns/docbook">
  <title>构造函数和析构函数</title>
@@ -129,7 +129,7 @@ class Point {
      </programlisting>
     </example>
     <para>
-     当构造器参数带访问控制（visibility modifier）时，PHP 会同时把它当作对象属性和构造器参数，
+     当构造器参数带修饰符时，PHP 会同时把它当作对象属性和构造器参数，
      并赋值到属性。
      构造器可以是空的，或者包含其他语句。
      参数值赋值到相应属性后执行正文中额外的代码语句。
@@ -138,6 +138,12 @@ class Point {
      并非所有参数都需要提升。可以混合提升或不提升参数作为属性，也不需要按顺序。
      提升后的参数不影响构造器内代码调用。
     </para>
+    <note>
+     <para>
+      使用<link linkend="language.oop5.visibility">可见性修饰符</link>（<literal>public</literal>、<literal>protected</literal>
+      或 <literal>private</literal>）是应用属性提升的最有可能的方式，但其它任何单个修饰符（例如 <literal>readonly</literal>）将产生相同的效果。
+     </para>
+    </note>
     <note>
      <para>
      对象属性的类型不能为 <type>callable</type> 以避免为引擎带来混淆。

diff --git a/language/operators/errorcontrol.xml b/language/operators/errorcontrol.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: 52407313885d27a4e891e08dd2e2481bcc39e244 Maintainer: mowangjuanzi Status: ready -->
+<!-- EN-Revision: 8d20b244cd76f802a31f5a9fc7ca8d97e2163391 Maintainer: mowangjuanzi Status: ready -->
 <sect1 xml:id="language.operators.errorcontrol">
  <title>错误控制运算符</title>
  <simpara>
@@ -14,7 +14,7 @@
  <warning>
   <para>
    PHP 8.0.0 之前，如果错误被 <literal>@</literal> 运算符抑制，则在自定义错误处理程序中调用 <function>error_reporting</function> 将始终返回
-   <literal>0</literal>。PHP 8.0.0 起，返回值为 <literal>E_ERROR | E_CORE_ERROR | E_COMPILE_ERROR | E_USER_ERROR | E_RECOVERABLE_ERROR | E_PARSE</literal>。
+   <literal>0</literal>。PHP 8.0.0 起，返回（按位）表达式的值：<literal>E_ERROR | E_CORE_ERROR | E_COMPILE_ERROR | E_USER_ERROR | E_RECOVERABLE_ERROR | E_PARSE</literal>。
   </para>
  </warning>
 

diff --git a/language/operators/increment.xml b/language/operators/increment.xml
@@ -1,22 +1,16 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: 52407313885d27a4e891e08dd2e2481bcc39e244 Maintainer: mowangjuanzi Status: ready -->
+<!-- EN-Revision: 02302a754aa0b2ea9a783f792e2c2c6c54230829 Maintainer: mowangjuanzi Status: ready -->
 <sect1 xml:id="language.operators.increment">
  <title>递增／递减运算符</title>
  <para>
-  PHP 支持 C 风格的前／后递增与递减运算符。
+  PHP 支持前／后递增与递减运算符。这些一元运算符允许将值递增或递减 1。
  </para>
- <note>
-  <simpara>
-   递增／递减运算符不影响布尔值。递减
-   &null; 值也没有效果，但是递增 &null; 的结果是 <literal>1</literal>。
-  </simpara>
- </note>
  <table>
   <title>递增／递减运算符</title>
   <tgroup cols="3">
    <thead>
     <row>
-     <entry>例子</entry>
+     <entry>示例</entry>
      <entry>名称</entry>
      <entry>效果</entry>
     </row>
@@ -45,46 +39,91 @@
    </tbody>
   </tgroup>
  </table>
+
  <para>
   一个简单的示例脚本：
   <informalexample>
    <programlisting role="php">
 <![CDATA[
 <?php
-echo "<h3>Postincrement</h3>";
+echo 'Post-increment:', PHP_EOL;
 $a = 5;
-echo "Should be 5: " . $a++ . "<br />\n";
-echo "Should be 6: " . $a . "<br />\n";
+var_dump($a++);
+var_dump($a);
 
-echo "<h3>Preincrement</h3>";
+echo 'Pre-increment:', PHP_EOL;
 $a = 5;
-echo "Should be 6: " . ++$a . "<br />\n";
-echo "Should be 6: " . $a . "<br />\n";
+var_dump(++$a);
+var_dump($a);
 
-echo "<h3>Postdecrement</h3>";
+echo 'Post-decrement:', PHP_EOL;
 $a = 5;
-echo "Should be 5: " . $a-- . "<br />\n";
-echo "Should be 4: " . $a . "<br />\n";
+var_dump($a--);
+var_dump($a);
 
-echo "<h3>Predecrement</h3>";
+echo 'Pre-decrement:', PHP_EOL;
 $a = 5;
-echo "Should be 4: " . --$a . "<br />\n";
-echo "Should be 4: " . $a . "<br />\n";
+var_dump(--$a);
+var_dump($a);
 ?>
 ]]>
    </programlisting>
+   &example.outputs;
+   <screen>
+<![CDATA[
+Post-increment:
+int(5)
+int(6)
+Pre-increment:
+int(6)
+int(6)
+Post-decrement:
+int(5)
+int(4)
+Pre-decrement:
+int(4)
+int(4)
+]]>
+   </screen>
   </informalexample>
+
+  <warning>
+   <para>
+    递增和递减运算符对 <type>bool</type> 类型值没有影响。自 PHP 8.3.0 起，会发出
+    <constant>E_WARNING</constant>，因为将来会默认将该值转换为 <type>int</type>。
+   </para>
+   <para>
+    递减运算符对 <type>null</type> 类型的值没有影响。自 PHP 8.3.0 起，会发出
+    <constant>E_WARNING</constant>，因为将来会默认将该值转换为 <type>int</type>。
+   </para>
+   <para>
+    递减运算符对非<link linkend="language.types.numeric-strings">数字字符串</link>没有影响。自
+    PHP 8.3.0 起，会发出 <constant>E_WARNING</constant>，因为在将来会抛出 <classname>TypeError</classname>。
+   </para>
+  </warning>
+  <note>
+   <para>
+    支持重载加/减法的内部对象也可以进行递增或递减。其中一个这样的内部对象是 <classname>GMP</classname>。
+   </para>
+  </note>
  </para>
- <para>
-  在处理字符变量的算数运算时，PHP 沿袭了 Perl 的习惯，而非 C 的。例如，在
-  Perl 中 <literal>$a = 'Z'; $a++;</literal> 将把 <literal>$a</literal>
-  变成<literal>'AA'</literal>，而在 C 中，<literal>a = 'Z'; a++;</literal> 将把
-  <literal>a</literal> 变成 <literal>'['</literal>（<literal>'Z'</literal>
-  的 ASCII 值是 90，<literal>'['</literal> 的 ASCII 值是
-  91）。注意字符变量只能递增，不能递减，并且只支持纯 ASCII 字母数字（a-z、A-Z 和
-  0-9）。递增/递减其他字符变量则无效，原字符串没有变化。
+
+ <sect2 xml:id="language.operators.increment.string">
+  <title>PERL 字符串递增功能</title>
+  <warning>
+   <simpara>
+    自 PHP 8.3.0 起，此功能已软弃用。应该使用 <function>str_increment</function> 函数。
+   </simpara>
+  </warning>
+
+  <para>
+   在 PHP 中，可以递增非<link linkend="language.types.numeric-strings">数字字符串</link>。该字符串必须是字母数字
+   ASCII 字符串。当到达字母 <literal>Z</literal> 且递增到下个字母时，将进位到左侧值。例如，<code>$a = 'Z';
+   $a++;</code>将 <varname>$a</varname> 变为 <literal>'AA'</literal>。
+  </para>
+
   <example>
-   <title>涉及字符变量的算数运算</title>
+   <title>PERL 字符串递减功能</title>
    <programlisting role="php">
 <![CDATA[
 <?php
@@ -132,8 +171,35 @@ A14
 ]]>
    </screen>
   </example>
- </para>
- <para>
-  递增或递减布尔值没有效果。
- </para>
+
+  <warning>
+   <para>
+    如果数字字母字符串可以解释为<link linkend="language.types.numeric-strings">数字字符串</link>，则将转换为
+    <type>int</type> 或 <type>float</type>。这对于看起来像以指数形式写出的浮点数字符串来说尤其是一个问题。<function>str_increment</function>
+    函数不会受到这些默认类型转换的影响。
+   </para>
+   <example>
+    <title>数字字母字符串转换为浮点数</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$s = "5d9";
+var_dump(++$s);
+var_dump(++$s);
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen>
+<![CDATA[
+string(3) "5e0"
+float(6)
+]]>
+    </screen>
+    <para>
+     这是因为值 <literal>"5e0"</literal> 解释为 <type>float</type>，并在递增之前转换为 <literal>5.0</literal>。
+    </para>
+   </example>
+  </warning>
+ </sect2>
 </sect1>
diff --git a/language/predefined/variables/httpresponseheader.xml b/language/predefined/variables/httpresponseheader.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: cb0630b14901459c0bf1556e7d68f1b4c0d3796e Maintainer: daijie Status: ready -->
-
+<!-- EN-Revision: c2cf2290247ae581d10dc4d74d91cc4f97293daa Maintainer: daijie Status: ready -->
+<!-- CREDITS: mowangjuanzi -->
 <phpdoc:varentry xmlns:phpdoc="http://php.net/ns/phpdoc" xml:id="reserved.variables.httpresponseheader" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" role="noversion">
  <refnamediv>
   <refname>$http_response_header</refname>
@@ -25,10 +25,10 @@
 <?php
 function get_contents() {
   file_get_contents("http://example.com");
-  var_dump($http_response_header);
+  var_dump($http_response_header); // 变量在本地作用域中填充
 }
 get_contents();
-var_dump($http_response_header);
+var_dump($http_response_header); // 调用 get_contents() 不会在函数作用域之外填充变量
 ?>
 ]]>
     </programlisting>
@@ -55,6 +55,8 @@ array(9) {
   [8]=>
   string(38) "Content-Type: text/html; charset=UTF-8"
 }
+
+Warning: Undefined variable $http_response_header
 NULL
 ]]>
     </screen>

diff --git a/language/types/string.xml b/language/types/string.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 48e35e9d0d985710d8f04ac998eb357b40bff9af Maintainer: dallas Status: ready -->
+<!-- EN-Revision: 3a13ca3690ebbcec05916a21c781685da2b60130 Maintainer: dallas Status: ready -->
 <!-- CREDITS: mowangjuanzi, Luffy -->
 <sect1 xml:id="language.types.string">
  <title>String 字符串</title>
@@ -158,21 +158,22 @@ echo 'Variables do not $expand $either';
       <row>
        <entry><literal>\[0-7]{1,3}</literal></entry>
        <entry>
-        符合该正则表达式序列的是一个以八进制方式来表达的字符，which silently overflows to fit in a byte
-        (e.g. "\400" === "\000")
+        八进制：匹配正则表达式序列 <literal>[0-7]{1,3}</literal> 的是八进制表示法的字符序列（比如
+        <literal>"\101" === "A"</literal>），会静默溢出以适应一个字节（例如 <literal>"\400" === "\000"</literal>）
        </entry>
       </row>
       <row>
        <entry><literal>\x[0-9A-Fa-f]{1,2}</literal></entry>
        <entry>
-        符合该正则表达式序列的是一个以十六进制方式来表达的字符
+        十六进制：匹配正则表达式序列 <literal>[0-9A-Fa-f]{1,2}</literal> 的是十六进制表示法的一个字符（比如
+        <literal>"\x41" === "A"</literal>）
        </entry>
       </row>
       <row>
        <entry><literal>\u{[0-9A-Fa-f]+}</literal></entry>
        <entry>
-        匹配正则表达式的字符序列是 unicode 码位，
-        该码位能作为 UTF-8 的表达方式输出字符串
+        Unicode：匹配正则表达式 <literal>[0-9A-Fa-f]+</literal> 的字符序列是 unicode 码位，该码位能作为
+        UTF-8 的表达方式输出字符串。序列中必须包含大括号。例如 <literal>"\u{41}" === "A"</literal>
        </entry>
       </row>
      </tbody>