com doc/zh: Remove some mentions of register globals see https://github.com/php/doc-en/commit/4a7ddddc272 71967b616ad3400cfbe2a9b4821 2b: reference/array/functions/extract.xml reference/n etwork/functions/setcookie.xml reference/session/examples .xml reference/strings/functions/parse-str.xml

[email protected] (Dai Jie) Sat, 16 Jan 2021 17:55:01 +0000
Newsgroups php.doc.zh
Message-ID <[email protected]>
Commit:    3a090dd0bafd1a079942542959011cf777508607
Author:    戴劼 <[email protected]>         Sun, 17 Jan 2021 01:55:01 +0800
Parents:   cb95b91f0fbfffd16954459a37f2c198d627dcbc
Branches:  master

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

Log:
Remove some mentions of register globals
see https://github.com/php/doc-en/commit/4a7ddddc27271967b616ad3400cfbe2a9b48212b

Changed paths:
  M  reference/array/functions/extract.xml
  M  reference/network/functions/setcookie.xml
  M  reference/session/examples.xml
  M  reference/strings/functions/parse-str.xml
diff_3a090dd0bafd1a079942542959011cf777508607.txt (text/plain, 17.3 KB)
diff --git a/reference/array/functions/extract.xml b/reference/array/functions/extract.xml
index 630e6172..e03323c5 100755
--- a/reference/array/functions/extract.xml
+++ b/reference/array/functions/extract.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: fd99f26061b9ee73010383bcea5b671143df1387 Maintainer: HonestQiao Status: ready -->
+<!-- EN-Revision: 4a7ddddc27271967b616ad3400cfbe2a9b48212b Maintainer: HonestQiao Status: ready -->
 <refentry xml:id="function.extract" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>extract</refname>
@@ -11,8 +11,8 @@
   <methodsynopsis>
    <type>int</type><methodname>extract</methodname>
    <methodparam><type>array</type><parameter role="reference">array</parameter></methodparam>
-   <methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer>EXTR_OVERWRITE</initializer></methodparam>
-   <methodparam choice="opt"><type>string</type><parameter>prefix</parameter><initializer>&null;</initializer></methodparam>
+   <methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer><constant>EXTR_OVERWRITE</constant></initializer></methodparam>
+   <methodparam choice="opt"><type>string</type><parameter>prefix</parameter><initializer>""</initializer></methodparam>
   </methodsynopsis>
   <para>
    本函数用来将变量从数组中导入到当前的符号表中。
@@ -20,6 +20,12 @@
   <para>
    检查每个键名看是否可以作为一个合法的变量名,同时也检查和符号表中已有的变量名的冲突。
   </para>
+  <warning>
+   <para>
+    不要对不可信的数据使用 <function>extract</function>,类似用户输入
+    (例如 <varname>$_GET</varname>、<varname>$_FILES</varname>)。
+   </para>
+  </warning>
  </refsect1>
  <refsect1 role="parameters">
   &reftitle.parameters;
@@ -191,97 +197,16 @@ blue, large, sphere, medium
   <warning>
    <para>
         不要对不能信任的数据使用
-    <function>extract</function>,例如用户的输入(<varname>$_GET</varname>, <varname>$_FILES</varname>,...)。如果这样做,举例说,要临时运行依赖于
-    <link linkend="security.globals">register_globals</link>
-    的老代码,要确保使用不会覆盖的
-    <parameter>extract_type</parameter> 值,例如
-    <constant>EXTR_SKIP</constant>,并且要留意应该按照 <link linkend="ini.variables-order">variables_order</link> 在 <link linkend="ini">&php.ini;</link> 里
+    <function>extract</function>,例如用户的输入(<varname>$_GET</varname>, <varname>$_FILES</varname>...)。
+    
+    如果这样做,要确保使用不会覆盖的
+    <parameter>flags</parameter> 值,例如
+    <constant>EXTR_SKIP</constant>,并且要留意应该按照
+     <link linkend="ini.variables-order">variables_order</link> 
+    在 <link linkend="ini">&php.ini;</link> 里
     定义的顺序来提取。
    </para>
   </warning>
-  <note>
-   <para>
-    If you still
-    have <link linkend="security.globals">register_globals</link>
-    and it is turned on, if you use <function>extract</function>
-    on <varname>$_FILES</varname> and
-    specify <constant>EXTR_SKIP</constant>, you may be surprised at
-    the results.
-   </para>
-   <warning>
-    <para>
-     This is not recommended practice and is only documented here for
-     completeness. The use
-     of <link linkend="security.globals">register_globals</link> is
-     deprecated and calling <function>extract</function> on untrusted
-     data such as <varname>$_FILES</varname> is, as noted above, a
-     potential security risk. If you encounter this issue, it means
-     that you are using at least two poor coding practices.
-    </para>
-   </warning>
-   <programlisting role="php">
-<![CDATA[
-<?php
-
-/* Suppose that $testfile is the name of a file upload input
-   and that register_globals is turned on. */
-
-var_dump($testfile);
-extract($_FILES, EXTR_SKIP);
-var_dump($testfile);
-var_dump($testfile['tmp_name']);
-
-?>
-]]>
-   </programlisting>
-   <simpara>
-    You might expect to see something like the following:
-   </simpara>
-   <screen>
-<![CDATA[
-string(14) "/tmp/phpgCCPX8"
-array(5) {
-  ["name"]=>
-  string(10) "somefile.txt"
-  ["type"]=>
-  string(24) "application/octet-stream"
-  ["tmp_name"]=>
-  string(14) "/tmp/phpgCCPX8"
-  ["error"]=>
-  int(0)
-  ["size"]=>
-  int(4208)
-}
-string(14) "/tmp/phpgCCPX8"
-]]>
-   </screen>
-   <simpara>
-    However, you would instead see something like this:
-   </simpara>
-   <screen>
-<![CDATA[
-string(14) "/tmp/phpgCCPX8"
-string(14) "/tmp/phpgCCPX8"
-string(1) "/"
-]]>
-   </screen>
-   <para>
-    This is due to the fact that
-    since <link linkend="security.globals">register_globals</link> is
-    turned on, <varname>$testfile</varname> already exists in the
-    global scope when <function>extract</function> is called. And
-    since <constant>EXTR_SKIP</constant> is
-    specified, <varname>$testfile</varname> is not overwritten with
-    the contents of the <constant>$_FILES</constant> array
-    so <varname>$testfile</varname> remains a string.
-    Because <link linkend="language.types.string.substr">strings may
-    be accessed using array syntax</link> and the non-numeric string
-    <literal>tmp_name</literal> is interpreted
-    as <literal>0</literal>, PHP
-    sees <varname>$testfile['tmp_name']</varname>
-    as <varname>$testfile[0]</varname>.
-   </para>
-  </note>
  </refsect1>
  <refsect1 role="seealso">
   &reftitle.seealso;
diff --git a/reference/network/functions/setcookie.xml b/reference/network/functions/setcookie.xml
index 3bb030c4..43ed226a 100644
--- a/reference/network/functions/setcookie.xml
+++ b/reference/network/functions/setcookie.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: d62d6b01c4d00cfebb7737054d19ba7ce26132d0 Maintainer: daijie Status: ready -->
+<!-- EN-Revision: 4a7ddddc27271967b616ad3400cfbe2a9b48212b Maintainer: daijie Status: ready -->
 <!-- Reviewed: no -->
 
 <refentry xml:id="function.setcookie" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
@@ -11,15 +11,22 @@
  
  <refsect1 role="description">
   &reftitle.description;
-  <methodsynopsis>
+  <methodsynopsis role="procedural">
    <type>bool</type><methodname>setcookie</methodname>
    <methodparam><type>string</type><parameter>name</parameter></methodparam>
    <methodparam choice="opt"><type>string</type><parameter>value</parameter><initializer>""</initializer></methodparam>
-   <methodparam choice="opt"><type>int</type><parameter>expire</parameter><initializer>0</initializer></methodparam>
+   <methodparam choice="opt"><type>int</type><parameter>expires</parameter><initializer>0</initializer></methodparam>
    <methodparam choice="opt"><type>string</type><parameter>path</parameter><initializer>""</initializer></methodparam>
    <methodparam choice="opt"><type>string</type><parameter>domain</parameter><initializer>""</initializer></methodparam>
-   <methodparam choice="opt"><type>bool</type><parameter>secure</parameter><initializer>false</initializer></methodparam>
-   <methodparam choice="opt"><type>bool</type><parameter>httponly</parameter><initializer>false</initializer></methodparam>
+   <methodparam choice="opt"><type>bool</type><parameter>secure</parameter><initializer>&false;</initializer></methodparam>
+   <methodparam choice="opt"><type>bool</type><parameter>httponly</parameter><initializer>&false;</initializer></methodparam>
+  </methodsynopsis>
+  <para>PHP 7.3.0 起有效的签名:</para>
+  <methodsynopsis role="procedural">
+   <type>bool</type><methodname>setcookie</methodname>
+   <methodparam><type>string</type><parameter>name</parameter></methodparam>
+   <methodparam choice="opt"><type>string</type><parameter>value</parameter><initializer>""</initializer></methodparam>
+   <methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>[]</initializer></methodparam>
   </methodsynopsis>
   <para>
    <function>setcookie</function> 定义了 Cookie,会和剩下的 HTTP 头一起发送给客户端。
@@ -57,7 +64,7 @@
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><parameter>expire</parameter></term>
+     <term><parameter>expires</parameter></term>
      <listitem>
       <para>
        Cookie 的过期时间。
@@ -70,7 +77,7 @@
       <para>
        <note>
         <para>
-          你可能注意到了,<parameter>expire</parameter> 使用 Unix 时间戳而非 <literal>Wdy, DD-Mon-YYYY
+          你可能注意到了,<parameter>expires</parameter> 使用 Unix 时间戳而非 <literal>Wdy, DD-Mon-YYYY
          HH:MM:SS GMT</literal> 这样的日期格式,是因为 PHP 内部作了转换。
         </para>
        </note>
@@ -121,11 +128,29 @@
        设置成 &true;,Cookie 仅可通过 HTTP 协议访问。
        这意思就是 Cookie 无法通过类似 JavaScript 这样的脚本语言访问。
        要有效减少 XSS 攻击时的身份窃取行为,可建议用此设置(虽然不是所有浏览器都支持),不过这个说法经常有争议。
-       PHP 5.2.0 中添加。
        &true; 或 &false;
       </para>
      </listitem>
     </varlistentry>
+    <varlistentry>
+        <term><parameter>options</parameter></term>
+        <listitem>
+            <para>
+                An associative <type>array</type> which may have any of the keys
+                <literal>expires</literal>, <literal>path</literal>, <literal>domain</literal>,
+                <literal>secure</literal>, <literal>httponly</literal> and <literal>samesite</literal>.
+                If any other key is present an error of level <constant>E_WARNING</constant>
+                is generated. The values have the same meaning as described for the 
+                parameters with the same name. The value of the <literal>samesite</literal>
+                element should be either <literal>None</literal>, <literal>Lax</literal>
+                or <literal>Strict</literal>.
+                If any of the allowed options are not given, their default values are the
+                same as the default values of the explicit parameters. If the
+                <literal>samesite</literal> element is omitted, no SameSite cookie
+                attribute is set.
+            </para>
+        </listitem>
+       </varlistentry>
    </variablelist>
   </para>
  </refsect1>
@@ -159,7 +184,7 @@ setcookie("TestCookie", $value, time()+3600, "/~rasmus/", "example.com", 1);
   </para>
   <para>
    注意:在发送 Cookie 时,值的部分会被自动 urlencode 编码。收到 Cookie 时,会自动解码,并赋值到可变的 Cookie 名称上。
-   如果不想被编码,可以使用 <function>setrawcookie</function> 代替——如果你的 PHP 版本是 5 及以上。
+   如果不想被编码,可以使用 <function>setrawcookie</function> 代替。
    在脚本里查看我们的测试 Cookie 的内容,使用下面的一个例子:
   </para>
   <para>
@@ -231,6 +256,13 @@ one : cookieone
 ]]>
     </screen>
    </example>
+   <note>
+    <simpara>
+     Using separator characters such as <literal>[</literal> and <literal>]</literal>
+     as part of the cookie name is not compliant to RFC 6265, section 4, but supposed
+     to be supported by user agents according to RFC 6265, section 5.
+    </simpara>
+   </note>
   </para>
  </refsect1>
 
@@ -247,17 +279,13 @@ one : cookieone
      </thead>
      <tbody>
       <row>
-       <entry>5.5.0</entry>
-       <entry>
-        发送给客户端的 Set-Cookie 头现在会包含 Max-Age 属性。
-       </entry>
-      </row>
-      <row>
-       <entry>5.2.0</entry>
-       <entry>
-        添加 <parameter>httponly</parameter> 参数。
-       </entry>
-      </row>
+        <entry>7.3.0</entry>
+        <entry>
+         An alternative signature supporting an <parameter>options</parameter>
+         array has been added. This signature supports also setting of the
+         SameSite cookie attribute.
+        </entry>
+       </row>
      </tbody>
     </tgroup>
    </informaltable>
@@ -274,14 +302,6 @@ one : cookieone
     或设置 <literal>output_buffering</literal> &php.ini; 或服务器配置文件里的配置指令。
    </para>
   </note>
-  <note>
-   <para>
-    如果 PHP 指令 <link linkend="ini.register-globals">register_globals</link>
-    设置成 <literal>on</literal>,Cookie 值会自动设置成变量。
-    下面的例子里会存在 <varname>$TestCookie</varname>。
-    我们推荐你使用 <varname>$_COOKIE</varname>。
-   </para>
-  </note>
   <para>
    注意避坑:
    <itemizedlist>
@@ -289,7 +309,7 @@ one : cookieone
      <simpara>
       在页面( Cookie 可见的页面)下次刷新前,Cookie 不会生效。
       测试 Cookie 是否已经成功设置,需要在下次页面加载时、Cookie 过期前检测。
-      过期时间是通过 <parameter>expire</parameter> 参数设置的。
+      过期时间是通过 <parameter>expires</parameter> 参数设置的。
       直接调用 <literal>print_r($_COOKIE);</literal> 调试检测 Cookie 是个很好的方式。
      </simpara>
     </listitem>
diff --git a/reference/session/examples.xml b/reference/session/examples.xml
index a6d806f1..04f33aea 100644
--- a/reference/session/examples.xml
+++ b/reference/session/examples.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 95bdd6883b5dde9504701777ba81b3c5f15df52b Maintainer: yuanyuqiang Status: ready -->
+<!-- EN-Revision: 4a7ddddc27271967b616ad3400cfbe2a9b48212b Maintainer: yuanyuqiang Status: ready -->
 <!-- Reviewed: no -->
 
 <appendix xml:id="session.examples" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
@@ -82,12 +82,6 @@ unset($_SESSION['count']);
     所以不可以将引用保存到会话变量中。
    </para>
   </warning>
-  <warning>
-   <para>
-    如果会话中存在和全局变量同名的变量,那么 register_globals 会导致全局变量被会话变量覆盖。
-    更多信息请参考 <link linkend="security.globals">注册全局变量</link>。
-   </para>
-  </warning>
   <note>
    <para>
     无论是通过调用函数 <function>session_start</function> 手动开启会话,
@@ -261,4 +255,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/strings/functions/parse-str.xml b/reference/strings/functions/parse-str.xml
index 8a6174f7..cc5bb947 100644
--- a/reference/strings/functions/parse-str.xml
+++ b/reference/strings/functions/parse-str.xml
@@ -1,8 +1,8 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: b84e653f7b2e6f6fbbcf8fa445921f73989f3fc0 Maintainer: daijie Status: ready -->
-<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.parse-str">
- <refnamediv>
+<!-- EN-Revision: 4a7ddddc27271967b616ad3400cfbe2a9b48212b Maintainer: daijie Status: ready -->
+<refentry xml:id="function.parse-str" xmlns="http://docbook.org/ns/docbook">
+    <refnamediv>
   <refname>parse_str</refname>
   <refpurpose>将字符串解析成多个变量</refpurpose>
  </refnamediv>
@@ -11,11 +11,11 @@
   &reftitle.description;
   <methodsynopsis>
    <type>void</type><methodname>parse_str</methodname>
-   <methodparam><type>string</type><parameter>encoded_string</parameter></methodparam>
-   <methodparam choice="opt"><type>array</type><parameter role="reference">result</parameter></methodparam>
+   <methodparam><type>string</type><parameter>string</parameter></methodparam>
+   <methodparam><type>array</type><parameter role="reference">result</parameter></methodparam>
   </methodsynopsis>
   <para>
-   如果 <parameter>encoded_string</parameter> 是 URL 传递入的查询字符串(query string),则将它解析为变量并设置到当前作用域(如果提供了 <parameter>result</parameter> 则会设置到该数组里 )。
+   如果 <parameter>string</parameter> 是 URL 传递入的查询字符串(query string),则将它解析为变量并设置到当前作用域(如果提供了 <parameter>result</parameter> 则会设置到该数组里 )。
   </para>
  </refsect1>
 
@@ -24,7 +24,7 @@
   <para>
    <variablelist>
     <varlistentry>
-     <term><parameter>encoded_string</parameter></term>
+     <term><parameter>string</parameter></term>
      <listitem>
       <para>
        输入的字符串。
@@ -41,13 +41,8 @@
 
       <warning>
        <para>
-        极度<emphasis>不建议</emphasis> 在没有 <parameter>result</parameter> 参数的情况下使用此函数,并且在  PHP 7.2 中将<emphasis>废弃</emphasis>不设置参数的行为。
-       </para>
-       <para>
-        在函数中动态设置变量会和 <link linkend="ini.register-globals">register_globals</link> 有同样的问题。
-       </para>
-       <para>
-        阅读「安全」中 <link linkend="security.globals">使用 Register Globals</link> 的章节,解释了它为什么是危险的。
+        极度<emphasis>不建议</emphasis> 在没有 <parameter>result</parameter> 参数的情况下使用此函数,
+        并且在  PHP 7.2 中将<emphasis>废弃</emphasis>不设置参数的行为。
        </para>
       </warning>
      </listitem>
@@ -75,6 +70,12 @@
       </row>
      </thead>
      <tbody>
+     <row>
+        <entry>8.0.0</entry>
+        <entry>
+         <parameter>result</parameter> 是必须项。
+        </entry>
+       </row>
       <row>
        <entry>7.2.0</entry>
        <entry>