com doc/zh: Update language/variables.xml: language/variables.xml

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

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

Log:
Update language/variables.xml

Changed paths:
  M  language/variables.xml
diff_cb95b91f0fbfffd16954459a37f2c198d627dcbc.txt (text/plain, 17.6 KB)
diff --git a/language/variables.xml b/language/variables.xml
index 07532309..54ceb194 100644
--- a/language/variables.xml
+++ b/language/variables.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 8b2059d6495c2f949d6739e294cf307f16ed9cc1 Maintainer: HonestQiao Status: ready -->
+<!-- EN-Revision: 4a7ddddc27271967b616ad3400cfbe2a9b48212b Maintainer: HonestQiao Status: ready -->
 <!-- CREDITS: dallas, Gregory, verdana -->
  <chapter xml:id="language.variables" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
   <title>变量</title>
@@ -14,17 +14,21 @@
 
    <para>
     变量名与 PHP
-    中其它的标签一样遵循相同的规则。一个有效的变量名由字母或者下划线开头,后面跟上任意数量的字母,数字,或者下划线。按照正常的正则表达式,它将被表述为:'<literal>[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*</literal>'。
+    中其它的标签一样遵循相同的规则。一个有效的变量名由字母或者下划线开头,后面跟上任意数量的字母,数字,或者下划线。
+    按照正常的正则表达式,它将被表述为:'<code>^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$</code>'。
    </para>
 
    <note>
     <simpara>
-     在此所说的字母是 a-z,A-Z,以及 ASCII 字符从 127 到 255(<literal>0x7f-0xff</literal>)。
+     在此所说的字母是 a-z,A-Z,以及 ASCII 字符从 128 到 255(<literal>0x80-0xff</literal>)。
     </simpara>
    </note>
    <note>
     <simpara>
      <literal>$this</literal> 是一个特殊的变量,它不能被赋值。
+     Prior to PHP 7.1.0, indirect assignment (e.g. by using
+     <link linkend="language.variables.variable">variable variables</link>)
+     was possible.
     </simpara>
    </note>
    
@@ -139,9 +143,8 @@ var_dump($unset_obj);
     </example>
    </para>
    <para>
-    依赖未初始化变量的默认值在某些情况下会有问题,例如把一个文件包含到另一个之中时碰上相同的变量名。另外把
-    <link linkend="ini.register-globals">register_globals</link> 打开是一个主要的<link 
-    linkend="security.globals">安全隐患</link>。使用未初始化的变量会发出
+    依赖未初始化变量的默认值在某些情况下会有问题,例如把一个文件包含到另一个之中时碰上相同的变量名。
+    使用未初始化的变量会发出
     <link linkend="errorfunc.constants.errorlevels.e-notice">E_NOTICE</link>
     错误,但是在向一个未初始化的数组附加单元时不会。<function>isset</function> 语言结构可以用来检测一个变量是否已被初始化。
    </para>
@@ -150,47 +153,19 @@ var_dump($unset_obj);
   <sect1 xml:id="language.variables.predefined">
    <title>预定义变量</title>
 
-   <simpara>
+   <para>
     PHP 提供了大量的预定义变量。由于许多变量依赖于运行的服务器的版本和设置,及其它因素,所以并没有详细的说明文档。一些预定义变量在
-    PHP 以<link linkend="features.commandline">命令行</link>形式运行时并不生效。有关这些变量的详细列表,请参阅<link
+    PHP 以<link linkend="features.commandline">命令行</link>形式运行时并不生效。
+    详细参阅<link
     linkend="reserved.variables">预定义变量</link>一章。
-   </simpara>
-
-   <warning>
-    <simpara>
-     PHP 4.2.0 以及后续版本中,PHP 指令 <link
-     linkend="ini.register-globals">register_globals</link> 的默认值为
-     <emphasis>off</emphasis>。这是 PHP 的一个主要变化。让 register_globals 的值为
-     <emphasis>off</emphasis> 将影响到预定义变量集在全局范围内的有效性。例如,为了得到
-     <varname>DOCUMENT_ROOT</varname> 的值,将必须使用
-     <varname>$_SERVER['DOCUMENT_ROOT']</varname> 代替
-     <varname>$DOCUMENT_ROOT</varname>,又如,使用
-     <varname>$_GET['id']</varname> 来代替 <varname>$id</varname> 从 URL
-     <literal>http://www.example.com/test.php?id=3</literal> 中获取
-     id 值,亦或使用 <varname>$_ENV['HOME']</varname> 来代替
-     <varname>$HOME</varname> 获取环境变量 HOME 的值。
-    </simpara>
-    <simpara>
-     更多相关信息,请阅读 <link
-     linkend="ini.register-globals">register_globals</link>
-     的配置项条目,安全一章中的<link
-     linkend="security.globals">使用 Register Globals</link>,以及 PHP
-     <link xlink:href="&url.php.release4.1.0;">4.1.0</link> 和
-     <link xlink:href="&url.php.release4.2.0;">4.2.0</link> 的发布公告。
-    </simpara>
-    <simpara>
-     如果有可用的 PHP 预定义变量那最好用,如<link
-     linkend="language.variables.superglobals">超全局数组</link>。
-    </simpara>
-   </warning>
+   </para>
 
-   <simpara>
-    从 PHP 4.1.0 开始,PHP 提供了一套附加的预定数组,这些数组变量包含了来自 web
+   <para>
+    PHP 提供了一套附加的预定数组,这些数组变量包含了来自 web
     服务器(如果可用),运行环境,和用户输入的数据。这些数组非常特别,它们在全局范围内自动生效,例如,在任何范围内自动生效。因此通常被称为自动全局变量(autoglobals)或者超全局变量(superglobals)。(PHP
-    中没有用户自定义超全局变量的机制。)超全局变量罗列于下文中;但是为了得到它们的内容和关于
-    PHP 预定义变量的进一步的讨论以及它们的本质,请参阅<link
-    linkend="reserved.variables">预定义变量</link>。而且,你也将注意到旧的预定义数组(<varname>$HTTP_*_VARS</varname>)仍旧存在。&avail.register-long-arrays;
-   </simpara>
+    中没有用户自定义超全局变量的机制。)
+    详情参阅<link linkend="language.variables.superglobals">超全局变量列表</link>。
+   </para>
 
    <note>
     <title>可变变量</title>
@@ -198,12 +173,6 @@ var_dump($unset_obj);
      超级全局变量不能被用作函数或类方法中的<link linkend="language.variables.variable">可变变量</link>。
     </para>
    </note>
-    <note>
-    <para>
-     尽管超全局变量和 HTTP_*_VARS
-     同时存在,但是它们并不是同一个变量,所以改变其中一个的值并不会对另一个产生影响。
-    </para>
-   </note>
 
    <para>
     如果某些 <link linkend="ini.variables-order">variables_order</link>
@@ -336,14 +305,8 @@ echo $b;
       <programlisting role="php">
 <![CDATA[
 <?php
-function test_global()
+function test_superglobal()
 {
-    // 大多数的预定义变量并不 "super",它们需要用 'global' 关键字来使它们在函数的本地区域中有效。
-    global $HTTP_POST_VARS;
-
-    echo $HTTP_POST_VARS['name'];
-
-    // Superglobals 在任何范围内都有效,它们并不需要 'global' 声明。Superglobals 是在 PHP 4.1.0 引入的。
     echo $_POST['name'];
 }
 ?>
@@ -439,10 +402,12 @@ function test()
      </example>
     </para>
 
-    <note>
-     <para>
-      静态变量可以按照上面的例子声明。如果在声明中用表达式的结果对其赋值会导致解析错误。
+    <para>
+        Static variables can be assigned values which are the,
+        result of constant expressions, but dynamic expressions, such as function
+        calls, will cause a parse error.
      </para>
+
      <para>
       <example>
        <title>声明静态变量</title>
@@ -451,8 +416,8 @@ function test()
 <?php
 function foo(){
     static $int = 0;          // correct
-    static $int = 1+2;        // wrong  (as it is an expression)
-    static $int = sqrt(121);  // wrong  (as it is an expression too)
+    static $int = 1+2;        // correct 
+    static $int = sqrt(121);  // wrong  (as it is a function)
 
     $int++;
     echo $int;
@@ -461,22 +426,17 @@ function foo(){
 ]]>
        </programlisting>
       </example>
-     </para>
-    </note>
+    </para>
+     
     <para>
      静态声明是在编译时解析的。
     </para>
-    <note>
-     <para>
-      在函数之外使用 <literal>global</literal> 关键字不算错。可以用于在一个函数之内包含文件时。
-     </para>
-    </note>
    </sect2>
 
    <sect2 xml:id="language.variables.scope.references">
     <title>全局和静态变量的引用</title>
     <simpara>
-     在 Zend 引擎 1 代,它驱动了 PHP4,对于变量的
+     对于变量的
      <link linkend="language.variables.scope.static">static</link> 和
      <link linkend="language.variables.scope.global">global</link>
      定义是以<link linkend="language.references">引用</link>的方式实现的。例如,在一个函数域内部用
@@ -490,12 +450,14 @@ function foo(){
 <?php
 function test_global_ref() {
     global $obj;
-    $obj = &new stdclass;
+    $new = new stdclass;
+    $obj = &$new;
 }
 
 function test_global_noref() {
     global $obj;
-    $obj = new stdclass;
+    $new = new stdclass;
+    $obj = $new;
 }
 
 test_global_ref();
@@ -510,9 +472,11 @@ var_dump($obj);
    &example.outputs;
 
     <screen>
+<![CDATA[
 NULL
-object(stdClass)(0) {
+object(stdClass)#1 (0) {
 }
+]]>
     </screen>
 
     <simpara>
@@ -530,10 +494,15 @@ function &get_instance_ref() {
     echo 'Static object: ';
     var_dump($obj);
     if (!isset($obj)) {
+        $new = new stdclass;
         // 将一个引用赋值给静态变量
-        $obj = &new stdclass;
+        $obj = &$new;
+    }
+    if (!isset($obj->property)) {
+        $obj->property = 1;
+    } else {
+        $obj->property++;
     }
-    $obj->property++;
     return $obj;
 }
 
@@ -543,10 +512,15 @@ function &get_instance_noref() {
     echo 'Static object: ';
     var_dump($obj);
     if (!isset($obj)) {
+        $new = new stdclass;
         // 将一个对象赋值给静态变量
-        $obj = new stdclass;
+        $obj = $new;
+    }
+    if (!isset($obj->property)) {
+        $obj->property = 1;
+    } else {
+        $obj->property++;
     }
-    $obj->property++;
     return $obj;
 }
 
@@ -563,14 +537,16 @@ $still_obj2 = get_instance_noref();
    &example.outputs;
 
     <screen>
+<![CDATA[
 Static object: NULL
 Static object: NULL
 
 Static object: NULL
-Static object: object(stdClass)(1) {
+Static object: object(stdClass)#3 (1) {
   ["property"]=>
   int(1)
 }
+]]>
     </screen>
 
     <simpara>
@@ -664,6 +640,7 @@ echo "$a $hello";
     并且其值将被用于 <varname>$foo</varname> 的属性名。对于 <varname>$bar</varname>
     是数组单元时也是一样。
    </simpara>
+   
    <simpara>
     也可使用花括号来给属性名清晰定界。最有用是在属性位于数组中,或者属性名包含有多个部分或者属性名包含有非法字符时(例如来自
     <function>json_decode</function> 或 <link linkend="book.simplexml">SimpleXML</link>)。
@@ -685,15 +662,14 @@ $foo = new foo();
 $bar = 'bar';
 $baz = array('foo', 'bar', 'baz', 'quux');
 echo $foo->$bar . "\n";
-echo $foo->$baz[1] . "\n";
+echo $foo->{$baz[1]} . "\n";
 
 $start = 'b';
 $end   = 'ar';
 echo $foo->{$start . $end} . "\n";
 
 $arr = 'arr';
-echo $foo->$arr[1] . "\n";
-echo $foo->{$arr}[1] . "\n";
+echo $foo->{$arr[1]} . "\n";
 
 ?>
 ]]>
@@ -704,7 +680,6 @@ I am bar.
 I am bar.
 I am bar.
 I am r.
-I am B.
      </screen>
     </example>
    </para>
@@ -727,7 +702,7 @@ I am B.
 
     <simpara>
      当一个表单提交给 PHP
-     脚本时,表单中的信息会自动在脚本中可用。有很多方法访问此信息,例如:
+     脚本时,表单中的信息会自动在脚本中可用。有几个方法访问此信息,例如:
     </simpara>
 
     <para>
@@ -746,39 +721,25 @@ I am B.
     </para>
 
     <para>
-     根据特定的设置和个人的喜好,有很多种方法访问 HTML
-     表单中的数据。例如:
+     只有两种方法可以访问 HTML
+     表单中的数据。
+     以下列出了当前有效的方法:
     </para>
 
-    <!-- FIXME PHP_6 register_long_arrays removal alert -->
     <para>
      <example>
       <title>从一个简单的 POST HTML 表单访问数据</title>
-      <programlisting role="html">
-<![CDATA[
-<?php
-// 自 PHP 4.1.0 起可用
-   echo $_POST['username'];
-   echo $_REQUEST['username'];
-   
-   import_request_variables('p', 'p_');
-   echo $p_username;
-
-// 自 PHP 5.0.0 起,这些长格式的预定义变量
-// 可用 register_long_arrays 指令关闭。
-
-   echo $HTTP_POST_VARS['username'];
-
-// 如果 PHP 指令 register_globals = on 时可用。不过自
-// PHP 4.2.0 起默认值为 register_globals = off。
-// 不提倡使用/依赖此种方法。
-
-   echo $username;
-?>
-]]>
+      <programlisting role="php">
+        <![CDATA[
+        <?php
+        echo $_POST['username'];
+        echo $_REQUEST['username'];
+        ?>
+        ]]>
       </programlisting>
      </example>
     </para>
+
     <para>
      使用 GET 表单也类似,只不过要用适当的 GET 预定义变量。GET
      也适用于
@@ -786,46 +747,17 @@ I am B.
      中在“?”之后的信息)。因此,举例说,<literal>http://www.example.com/test.php?id=3</literal>
      包含有可用 <varname>$_GET['id']</varname>
      来访问的 GET 数据。参见
-     <link linkend="reserved.variables.request">$_REQUEST</link> 和
-     <function>import_request_variables</function>。
+     <link linkend="reserved.variables.request">$_REQUEST</link>。
     </para>
 
     <note>
      <para>
-      <link linkend="language.variables.superglobals">超全局数组</link>例如
-      <varname>$_POST</varname> 和 <varname>$_GET</varname>,自
-      PHP 4.1.0 起可用。
-     </para>
-    </note>
-
-    <note>
-     <para>
       变量名中的点和空格被转换成下划线。例如
       <literal>&lt;input name="a.b" /&gt;</literal> 变成了
       <literal>$_REQUEST["a_b"]</literal>。
      </para>
     </note>
 
-    <para>
-     如上所示,在 PHP 4.2.0 之前 <link
-     linkend="ini.register-globals">register_globals</link>
-     的默认值是
-     <emphasis>on</emphasis>。PHP
-     社区鼓励大家不要依赖此指令,建议在编码时假定其为
-     <emphasis>off</emphasis>。
-    </para>
-
-    <note>
-     <para>
-      <link linkend="ini.magic-quotes-gpc">magic_quotes_gpc</link>
-      配置指令影响到
-      Get,Post 和 Cookie 的值。如果打开,值 (It's "PHP!") 会自动转换成
-      (It\'s \"PHP!\")。十多年前对数据库的插入需要如此转义,如今已经过时了,应该关闭。参见
-      <function>addslashes</function>,<function>stripslashes</function> 和
-      magic_quotes_sybase。
-     </para>
-    </note>
-
     <simpara>
      PHP 也懂得表单变量上下文中的数组(参见<link
      linkend="faq.html">相关常见问题</link>)。例如可以将相关的变量编成组,或者用此特性从多选输入框中取得值。例如,将一个表单 POST 给自己并在提交时显示数据:
@@ -866,6 +798,14 @@ if (isset($_POST['action']) && $_POST['action'] == 'submitted') {
      </example>
     </para>
 
+    <note>
+        <simpara>
+         If an external variable name begins with a valid array syntax, trailing characters
+         are silently ignored. For example, <literal>&lt;input name="foo[bar]baz"&gt;</literal>
+         becomes <literal>$_REQUEST['foo']['bar']</literal>.
+        </simpara>
+     </note>
+
      <sect3 xml:id="language.variables.external.form.submit">
      <title>IMAGE SUBMIT 变量名</title>
 
@@ -905,11 +845,18 @@ if (isset($_POST['action']) && $_POST['action'] == 'submitted') {
      SetCookie 函数必须在向浏览器发送任何输出之前调用。对于
      <function>header</function> 函数也有同样的限制。Cookie
      数据会在相应的 cookie 数据数组中可用,例如
-     <varname>$_COOKIE</varname>,<varname>$HTTP_COOKIE_VARS</varname> 和
+     <varname>$_COOKIE</varname> 和
      <varname>$_REQUEST</varname>。更多细节和例子见
      <function>setcookie</function> 手册页面。
     </simpara>
 
+    <note>
+        <simpara>
+         As of PHP 7.2.34, 7.3.23 and 7.4.11, respectively, the <emphasis>names</emphasis>
+         of incoming cookies are no longer url-decoded for security reasons.
+        </simpara>
+    </note>
+
     <simpara>
      如果要将多个值赋给一个 cookie 变量,必须将其赋成数组。例如:
     </simpara>
@@ -991,8 +938,46 @@ $varname.ext;  /* 非法变量名 */
      和 <function>is_string</function>。参见<link
      linkend="language.types">类型</link>一章。
     </para>
+    <para>
+     HTTP being a text protocol, most, if not all, content that comes in
+     <link linkend="language.variables.superglobals">Superglobal arrays</link>, 
+     like <varname>$_POST</varname> and <varname>$_GET</varname> will remain
+     as strings. PHP will not try to convert values to a specific type.
+     In the example below, <varname>$_GET["var1"]</varname> will contain the
+     string "null" and <varname>$_GET["var2"]</varname>, the string "123".
+     <programlisting>
+<![CDATA[
+/index.php?var1=null&var2=123
+]]>
+      </programlisting>
+    </para>
    </sect2>
+   
+   <sect2 xml:id="language.variables.external.changelog">
+    &reftitle.changelog;
 
+    <para>
+     <informaltable>
+      <tgroup cols="2">
+       <thead>
+        <row>
+         <entry>&Version;</entry>
+         <entry>&Description;</entry>
+        </row>
+       </thead>
+       <tbody>
+        <row>
+         <entry>7.2.34, 7.3.23, 7.4.11</entry>
+         <entry>
+            The <emphasis>names</emphasis> of incoming cookies are no longer url-decoded
+            for security reasons.
+         </entry>
+        </row>
+       </tbody>
+      </tgroup>
+     </informaltable>
+    </para>
+   </sect2>
   </sect1>
 
  </chapter>