com doc/zh: Sync with en: appendices/ini.list.xml reference/outcontrol/ini.xml reference/session/ini.xml

[email protected] (Dai Jie) Sat, 16 Jan 2021 16:54:36 +0000
Newsgroups php.doc.zh
Message-ID <[email protected]>
Commit:    ae83acd9d8eaaafa1c6bbfec993de9c85e71d030
Author:    戴劼 <[email protected]>         Sun, 17 Jan 2021 00:54:36 +0800
Parents:   f1852a15df12d59d044e38e33530e344a6922629
Branches:  master

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

Log:
Sync with en

Changed paths:
  M  appendices/ini.list.xml
  M  reference/outcontrol/ini.xml
  M  reference/session/ini.xml
diff_ae83acd9d8eaaafa1c6bbfec993de9c85e71d030.txt (text/plain, 21.1 KB)
diff --git a/appendices/ini.list.xml b/appendices/ini.list.xml
index 213ed531..8cb4e377 100644
--- a/appendices/ini.list.xml
+++ b/appendices/ini.list.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
 <!-- $Author$ -->
-<!-- EN-Revision: d278431ef5e561787093a7b2679327a615b09367 Maintainer: Avenger Status: ready -->
+<!-- EN-Revision: f3d6ada6156b28791a28efebe2e5c070159c3a94 Maintainer: Avenger Status: ready -->
 
 <section xml:id="ini.list" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
   <title>&php.ini; 配置选项列表</title>
@@ -1948,18 +1948,6 @@
        <entry>PHP &lt;= 5.4.19 and 和 PHP &lt;= 5.5.1 时,是 PHP_INI_ALL。</entry>
       </row>
       <row>
-       <entry><link linkend="ini.session.bug-compat-42">session.bug_compat_42</link></entry>
-       <entry>"1"</entry>
-       <entry>PHP_INI_ALL</entry>
-       <entry>从 PHP 4.3.0 起可用。 在 PHP 5.4.0 中移除该选项。</entry>
-      </row>
-      <row>
-       <entry><link linkend="ini.session.bug-compat-warn">session.bug_compat_warn</link></entry>
-       <entry>"1"</entry>
-       <entry>PHP_INI_ALL</entry>
-       <entry> 在 PHP 5.4.0 中移除该选项。</entry>
-      </row>
-      <row>
        <entry><link linkend="ini.session.cache-expire">session.cache_expire</link></entry>
        <entry>"180"</entry>
        <entry>PHP_INI_ALL</entry>
diff --git a/reference/outcontrol/ini.xml b/reference/outcontrol/ini.xml
index 620b5c05..91c1ad8e 100644
--- a/reference/outcontrol/ini.xml
+++ b/reference/outcontrol/ini.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: a9b26c34e481fa948bcc7d75b73b441605142dd7 Maintainer: HonestQiao Status: ready -->
+<!-- EN-Revision: 86e6094e86b84a51d00ab217ac50ce8dde33d82a Maintainer: HonestQiao Status: ready -->
 <!-- Reviewed: no Maintainer: HonestQiao -->
 <section xml:id="outcontrol.configuration" xmlns="http://docbook.org/ns/docbook">
  &reftitle.runtime;
@@ -28,13 +28,27 @@
      <entry>output_handler</entry>
      <entry>NULL</entry>
      <entry>PHP_INI_PERDIR</entry>
-     <entry>自 PHP 4.0.4 起可用</entry>
+     <entry></entry>
     </row>
     <row>
      <entry>implicit_flush</entry>
      <entry>"0"</entry>
      <entry>PHP_INI_ALL</entry>
-     <entry>在 PHP &lt;= 4.2.3 版本中是 PHP_INI_PERDIR</entry>
+     <entry></entry>
+    </row>
+    <row>
+        <entry><link linkend="ini.url-rewriter.tags">url_rewriter.tags</link></entry>
+        <entry>"a=href,area=href,frame=src,form=,fieldset="</entry>
+        <entry>PHP_INI_ALL</entry>
+        <entry>Before PHP 7.1.0, this was used to set
+        session's trans sid rewrite. From PHP 7.1.0, it is only used by 
+        <function>output_add_rewrite_var</function>.</entry>
+    </row>
+    <row>
+        <entry><link linkend="ini.url-rewriter.hosts">url_rewriter.hosts</link></entry>
+        <entry><literal>$_SERVER['HTTP_HOST']</literal> is used as default.</entry>
+        <entry>PHP_INI_ALL</entry>
+        <entry>Available as of PHP 7.1.0</entry>
     </row>
     </tbody>
    </tgroup>
@@ -49,14 +63,14 @@
   <varlistentry xml:id="ini.output-buffering">
    <term>
     <parameter>output_buffering</parameter>
-    <type>boolean</type>/<type>integer</type>
+    <type>bool</type>/<type>int</type>
    </term>
    <listitem>
     <para>
      该选项设置为 On
      时,将在所有的脚本中使用输出控制。如果要限制输出缓冲区的最大值,可将该选项设定为指定的最大字节数(例如
      output_buffering=4096)。从PHP
-     4.3.5 版开始,该选项在 PHP-CLI 下总是为 Off。
+     该选项在 PHP-CLI 下总是为 Off。
     </para>
    </listitem>
   </varlistentry>
@@ -91,7 +105,7 @@
   <varlistentry xml:id="ini.implicit-flush">
    <term>
     <parameter>implicit_flush</parameter>
-    <type>boolean</type>
+    <type>bool</type>
    </term>
    <listitem>
     <para>
@@ -111,7 +125,49 @@
     </para>
    </listitem>
   </varlistentry>
- </variablelist>
+
+  <varlistentry xml:id="ini.url-rewriter.tags">
+    <term>
+     <parameter>url_rewriter.tags</parameter>
+     <type>string</type>
+    </term>
+    <listitem>
+     <simpara>
+      <literal>url_rewriter.tags</literal> specifies which HTML tags
+      are rewritten by <function>output_add_rewrite_var</function> values.
+      Defaults to
+      <literal>a=href,area=href,frame=src,input=src,form=</literal>
+     </simpara>
+     <simpara>
+      <literal>form</literal> is special tag. <literal>&lt;input hidden="session_id" name="session_name"&gt;</literal>
+      is added as form variable.
+     </simpara>
+     <note>
+      <simpara>
+       Before PHP 7.1.0, <link linkend="ini.url-rewriter.tags">url_rewriter.tags</link>
+       was used to specify <link linkend="ini.session.trans-sid-tags">session.trans_sid_tags</link>.
+       As of PHP 7.1.0, <literal>fieldset</literal> is no longer considered as special tag.
+      </simpara>
+     </note>
+    </listitem>
+   </varlistentry>
+
+    <varlistentry xml:id="ini.url-rewriter.hosts">
+        <term>
+        <parameter>url_rewriter.hosts</parameter>
+        <type>string</type>
+        </term>
+        <listitem>
+        <simpara>
+        <literal>url_rewriter.hosts</literal> specifies which hosts are
+        rewritten to include <function>output_add_rewrite_var</function> values.
+        Defaults to <literal>$_SERVER['HTTP_HOST']</literal>. Multiple hosts
+        can be specified by ",", no space is allowed between hosts. e.g.
+        <literal>php.net,wiki.php.net,bugs.php.net</literal>
+        </simpara>
+        </listitem>
+    </varlistentry>
+  </variablelist>
  </para>
 </section>
 
@@ -135,4 +191,3 @@ vim600: syn=xml fen fdm=syntax fdl=2 si
 vim: et tw=78 syn=sgml
 vi: ts=1 sw=1
 -->
-
diff --git a/reference/session/ini.xml b/reference/session/ini.xml
index 1f12fe0f..5a26be12 100644
--- a/reference/session/ini.xml
+++ b/reference/session/ini.xml
@@ -240,18 +240,6 @@
      <entry>PHP_INI_ALL</entry>
      <entry>自 PHP 7.1.0 起移除。</entry>
     </row>
-    <row>
-     <entry><link linkend="ini.session.bug-compat-42">session.bug_compat_42</link></entry>
-     <entry>"1"</entry>
-     <entry>PHP_INI_ALL</entry>
-     <entry>自 PHP 5.4.0 起移除。</entry>
-    </row>
-    <row>
-     <entry><link linkend="ini.session.bug-compat-warn">session.bug_compat_warn</link></entry>
-     <entry>"1"</entry>
-     <entry>PHP_INI_ALL</entry>
-     <entry>自 PHP 5.4.0 起移除。</entry>
-    </row>
    </tbody>
   </tgroup>
  </table>
@@ -268,12 +256,14 @@
    </term>
    <listitem>
     <simpara>
-     <literal>session.save_handler</literal> 定义了来存储和获取与会话关联的数据的处理器的名字。默认为
-     <literal>files</literal>。Note that individual extensions may register
+     <literal>session.save_handler</literal> defines the name of the
+     handler which is used for storing and retrieving data
+     associated with a session. Defaults to
+     <literal>files</literal>. Note that individual extensions may register
      their own <literal>save_handler</literal>s; registered handlers can be
      obtained on a per-installation basis by referring to
-     <function>phpinfo</function>. 参见
-     <function>session_set_save_handler</function>。
+     <function>phpinfo</function>. See also
+     <function>session_set_save_handler</function>.
     </simpara>
    </listitem>
   </varlistentry>
@@ -320,11 +310,6 @@
       仅仅在绝对肯定站点足够大时,才可以设置 <literal>N</literal> 大于2。
      </para>
     </caution>
-    <note>
-     <simpara>
-      在 PHP 4.3.6 之前,Windows 用户必须修改此选项以使用 PHP 的会话函数。必须指定一个合法路径,例如:<filename>c:/temp</filename>。
-     </simpara>
-    </note>
    </listitem>
   </varlistentry>
 
@@ -401,7 +386,7 @@
   <varlistentry xml:id="ini.session.gc-divisor">
    <term>
     <parameter>session.gc_divisor</parameter>
-    <type>integer</type>
+    <type>int</type>
    </term>
    <listitem>
     <simpara>
@@ -418,7 +403,7 @@
   <varlistentry xml:id="ini.session.gc-maxlifetime">
    <term>
     <parameter>session.gc_maxlifetime</parameter>
-    <type>integer</type>
+    <type>int</type>
    </term>
    <listitem>
     <simpara>
@@ -469,6 +454,9 @@
      设置  <literal>session.entropy_length</literal> 为非零的值将使 PHP 使用 Windows Random API 作为熵值源。
     </simpara>
     <note>
+      <simpara>
+       PHP 7.1.0 中移除。
+      </simpara>
      <simpara>
       自 PHP 5.4.0 起,默认情况下, <literal>session.entropy_file</literal> 在 <literal>/dev/urandom</literal> 或 <literal>/dev/arandom</literal> 可用的时候使用它们。
       在 PHP 5.3.0 中此指令默认留空。
@@ -480,31 +468,51 @@
   <varlistentry xml:id="ini.session.entropy-length">
    <term>
     <parameter>session.entropy_length</parameter>
-    <type>integer</type>
+    <type>int</type>
    </term>
    <listitem>
     <simpara>
      <literal>session.entropy_length</literal> 指定了从上面的文件中读取的字节数。默认为
      <literal>0</literal>(禁用)。
     </simpara>
+    <simpara>
+      PHP 7.1.0 中移除。
+    </simpara>
    </listitem>
   </varlistentry>
 
   <varlistentry xml:id="ini.session.use-strict-mode">
    <term>
     <parameter>session.use_strict_mode</parameter>
-    <type>boolean</type>
+    <type>bool</type>
    </term>
    <listitem>
     <simpara>
      <literal>session.use_strict_mode</literal> specifies whether the
      module will use strict session id mode. If this mode is enabled,
-     the module does not accept uninitialized session ID. If uninitialized
-     session ID is sent from browser, new session ID is sent to browser.
+     the module does not accept uninitialized session IDs. If an uninitialized
+     session ID is sent from the browser, a new session ID is sent to the browser.
      Applications are protected from session fixation via session adoption
      with strict mode.
      Defaults to <literal>0</literal> (disabled).
     </simpara>
+    <note>
+     <simpara>
+     Enabling <literal>session.use_strict_mode</literal> is mandatory for
+     general session security. All sites are advised to enable this. See 
+     <function>session_create_id</function> example code for more details.
+     </simpara>
+    </note>
+    <warning>
+     <para>
+      If a custom session handler registered via <function>session_set_save_handler</function>
+      does not implement <methodname>SessionUpdateTimestampHandlerInterface::validateId</methodname>,
+      nor supplies the <parameter>validate_sid</parameter> callback, respectively,
+      strict session ID mode is effectively disabled, regardless of the value of this directive.
+      Particularly note that <classname>SessionHandler</classname> does <emphasis>not</emphasis>
+      implement <methodname>SessionHandler::validateId</methodname>.
+     </para>
+    </warning>
    </listitem>
   </varlistentry>
 
@@ -592,7 +600,7 @@
   <varlistentry xml:id="ini.session.cookie-secure">
    <term>
     <parameter>session.cookie_secure</parameter>
-    <type>boolean</type>
+    <type>bool</type>
    </term>
    <listitem>
     <simpara>
@@ -607,7 +615,7 @@
   <varlistentry xml:id="ini.session.cookie-httponly">
    <term>
     <parameter>session.cookie_httponly</parameter>
-    <type>boolean</type>
+    <type>bool</type>
    </term>
    <listitem>
     <simpara>
@@ -648,9 +656,12 @@
    <listitem>
     <simpara>
      <literal>session.cache_limiter</literal>
-     指定会话页面所使用的缓冲控制方法(none/nocache/private/private_no_expire/public)。默认为
+     指定会话页面所使用的缓冲控制方法(
+     <literal>none</literal>/<literal>nocache</literal>/
+     <literal>private</literal>/<literal>
+       private_no_expire</literal>/<literal>public</literal>)。默认为
      <literal>nocache</literal>。参见
-     <function>session_cache_limiter</function>。
+     <function>session_cache_limiter</function> 文档查看各个值的含义。
     </simpara>
    </listitem>
   </varlistentry>
@@ -659,7 +670,7 @@
   <varlistentry xml:id="ini.session.cache-expire">
    <term>
     <parameter>session.cache_expire</parameter>
-    <type>integer</type>
+    <type>int</type>
    </term>
    <listitem>
     <simpara>
@@ -673,7 +684,7 @@
   <varlistentry xml:id="ini.session.use-trans-sid">
    <term>
     <parameter>session.use_trans_sid</parameter>
-    <type>boolean</type>
+    <type>bool</type>
    </term>
    <listitem>
     <simpara>
@@ -696,30 +707,30 @@
   </varlistentry>
 
   <varlistentry xml:id="ini.session.trans-sid-tags">
-   <term>
-    <parameter>session.trans_sid_tags</parameter>
-    <type>string</type>
-   </term>
-   <listitem>
-    <simpara>
-     <literal>session.trans_sid_tags</literal> specifies which HTML tags
-     are rewritten to include session id when transparent sid support
-     is enabled. Defaults to
-     <literal>a=href,area=href,frame=src,input=src,form=</literal>
-    </simpara>
-    <simpara>
-     <literal>form</literal> is special tag. <literal>&lt;input hidden="session_id" name="session_name"&gt;</literal>
-     is added as form variable.
-    </simpara>
-    <note>
+    <term>
+     <parameter>session.trans_sid_tags</parameter>
+     <type>string</type>
+    </term>
+    <listitem>
      <simpara>
-      Before PHP 7.1.0, <link linkend="ini.url-rewriter.tags">url_rewriter.tags</link>
-      was used for this purpose. Since PHP 7.1.0, <literal>fieldset</literal> 
-      is no longer considered as special tag.
+      <literal>session.trans_sid_tags</literal> specifies which HTML tags
+      are rewritten to include session id when transparent sid support
+      is enabled. Defaults to
+      <literal>a=href,area=href,frame=src,input=src,form=</literal>
      </simpara>
-    </note>
-   </listitem>
-  </varlistentry>
+     <simpara>
+      <literal>form</literal> is special tag. <literal>&lt;input hidden="session_id" name="session_name"&gt;</literal>
+      is added as form variable.
+     </simpara>
+     <note>
+      <simpara>
+       Before PHP 7.1.0, <link linkend="ini.url-rewriter.tags">url_rewriter.tags</link>
+       was used for this purpose. Since PHP 7.1.0, <literal>fieldset</literal> 
+       is no longer considered as special tag.
+      </simpara>
+     </note>
+    </listitem>
+   </varlistentry>
 
   <varlistentry xml:id="ini.session.trans-sid-hosts">
    <term>
@@ -736,138 +747,72 @@
     </simpara>
    </listitem>
   </varlistentry>
-  
-  <varlistentry xml:id="ini.session.bug-compat-42">
-   <term>
-    <parameter>session.bug_compat_42</parameter>
-    <type>boolean</type>
-   </term>
-   <listitem>
-    <simpara>
-     PHP 4.2.3 以及更低版本有一个未公开的特性/错误,它允许用户在
-     <link linkend="ini.register-globals">register_globals</link>
-     被禁用的情况下在全局范围内初始化一个会话变量。PHP 4.3.0
-     及更高版本会在使用此特性时并且启用了
-     <link linkend="ini.session.bug-compat-warn">session.bug_compat_warn</link>
-     时发出警告。此特性/错误可以通过关闭此选项而禁用。
-    </simpara>
-    <note>
-     <simpara>
-       PHP 5.4.0 中已经移除。
-     </simpara>
-    </note>
-   </listitem>
-  </varlistentry>
-  
-  <varlistentry xml:id="ini.session.bug-compat-warn">
-   <term>
-    <parameter>session.bug_compat_warn</parameter>
-    <type>boolean</type>
-   </term>
-   <listitem>
-    <simpara>
-     PHP 4.2.3 以及更低版本有一个未公开的特性/错误,它允许用户在
-     <link linkend="ini.register-globals">register_globals</link>
-     被禁用的情况下在全局范围内初始化一个会话变量。PHP 4.3.0
-     及更高版本会在使用此特性时并且同时启用了
-     <link linkend="ini.session.bug-compat-42">session.bug_compat_42</link> 和
-     <link linkend="ini.session.bug-compat-warn">session.bug_compat_warn</link>
-     时发出警告。
-    </simpara>
-    <note>
-     <simpara>
-       PHP 5.4.0 中已经移除。
-     </simpara>
-    </note>
-   </listitem>
-  </varlistentry>
 
   <varlistentry xml:id="ini.session.sid-length">
-   <term>
-    <parameter>session.sid_length</parameter>
-    <type>integer</type>
-   </term>
-   <listitem>
-    <simpara>
-     <literal>session.sid_length</literal> allows you to specify the
-     length of session ID string. Session ID length can be between 22
-     to 256.
-    </simpara>
-    <simpara>
-     The default is 32. If you need compatibility you may specify 32,
-     40, etc. Longer session ID is harder to guess. At least 32 chars
-     are recommended.
-    </simpara>
-    <tip>
-     <para>
-      Compatibility Note: Use 32 instead of
-      <literal>session.hash_function</literal>=0 (MD5) and
-      <literal>session.hash_bits_per_character</literal>=4,
-      <literal>session.hash_function</literal>=1 (SHA1) and
-      <literal>session.hash_bits_per_character</literal>=6. Use 26 instead of
-      <literal>session.hash_function</literal>=0 (MD5) and
-      <literal>session.hash_bits_per_character</literal>=5. Use 22 instead of
-      <literal>session.hash_function</literal>=0 (MD5) and
-      <literal>session.hash_bits_per_character</literal>=6. You must
-      configure INI values to have at least 128 bits in session ID. Do
-      not forget to set an appropriate value for
-      <literal>session.sid_bits_per_character</literal>, otherwise you
-      will have weaker session ID.
-     </para>
-    </tip> 
-    <note>
+    <term>
+     <parameter>session.sid_length</parameter>
+     <type>int</type>
+    </term>
+    <listitem>
      <simpara>
-      This setting is introduced in PHP 7.1.0.
+      <literal>session.sid_length</literal> allows you to specify the
+      length of session ID string. Session ID length can be between 22
+      to 256.
      </simpara>
-    </note>
-   </listitem>
-  </varlistentry>
-
-  <varlistentry xml:id="ini.session.sid-bits-per-character">
-   <term>
-    <parameter>session.sid_bits_per_character</parameter>
-    <type>integer</type>
-   </term>
-   <listitem>
-    <simpara>
-     <literal>session.sid_per_character</literal> allows you to specify the
-     number of bits in encoded session ID character. The possible values are 
-     '4' (0-9, a-f), '5' (0-9, a-v), and '6' (0-9, a-z, A-Z, "-", ",").
-    </simpara>
-    <simpara>
-     The default is 4. The more bits results in stronger session ID. 5 is
-     recommended value for most environments.
-    </simpara>
-    <para>
-    </para>
-    <note>
      <simpara>
-      This setting is introduced in PHP 7.1.0.
+      The default is 32. If you need compatibility you may specify 32,
+      40, etc. Longer session ID is harder to guess. At least 32 chars
+      are recommended.
      </simpara>
-    </note>
-   </listitem>
-  </varlistentry>
-
-
-  <varlistentry xml:id="ini.url-rewriter.tags">
-   <term>
-    <parameter>url_rewriter.tags</parameter>
-    <type>string</type>
-   </term>
-   <listitem>
-    <simpara>
-     <literal>url_rewriter.tags</literal> 指定在使用透明 SID 支持时哪些 HTML
-     标记会被修改以加入会话 ID。默认为
-     <literal>a=href,area=href,frame=src,input=src,form=fakeentry,fieldset=</literal>。
-    </simpara>
-    <note>
+     <tip>
+      <para>
+       Compatibility Note: Use 32 instead of
+       <literal>session.hash_function</literal>=0 (MD5) and
+       <literal>session.hash_bits_per_character</literal>=4,
+       <literal>session.hash_function</literal>=1 (SHA1) and
+       <literal>session.hash_bits_per_character</literal>=6. Use 26 instead of
+       <literal>session.hash_function</literal>=0 (MD5) and
+       <literal>session.hash_bits_per_character</literal>=5. Use 22 instead of
+       <literal>session.hash_function</literal>=0 (MD5) and
+       <literal>session.hash_bits_per_character</literal>=6. You must
+       configure INI values to have at least 128 bits in session ID. Do
+       not forget to set an appropriate value for
+       <literal>session.sid_bits_per_character</literal>, otherwise you
+       will have weaker session ID.
+      </para>
+     </tip> 
+     <note>
+      <simpara>
+       This setting is introduced in PHP 7.1.0.
+      </simpara>
+     </note>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry xml:id="ini.session.sid-bits-per-character">
+    <term>
+     <parameter>session.sid_bits_per_character</parameter>
+     <type>int</type>
+    </term>
+    <listitem>
      <simpara>
-      如果要符合 XHTML,去掉 <literal>form</literal> 项并在表单字段前后加上
-      &lt;fieldset&gt; 标记。
+      <literal>session.sid_per_character</literal> allows you to specify the
+      number of bits in encoded session ID character. The possible values are 
+      '4' (0-9, a-f), '5' (0-9, a-v), and '6' (0-9, a-z, A-Z, "-", ",").
      </simpara>
-    </note>
-   </listitem>
-  </varlistentry>
+     <simpara>
+      The default is 4. The more bits results in stronger session ID. 5 is
+      recommended value for most environments.
+     </simpara>
+     <para>
+     </para>
+     <note>
+      <simpara>
+       This setting is introduced in PHP 7.1.0.
+      </simpara>
+     </note>
+    </listitem>
+   </varlistentry>
 
   <varlistentry xml:id="ini.session.hash-function">
    <term>