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>