php-doc-en/reference/http/functions/setcookie.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Author: avenger $ -->
<!-- $Revision: 1.7 $ -->
<!-- splitted from ./en/functions/http.xml, last change in rev 1.2 -->
  <refentry id="function.setcookie">
   <refnamediv>
    <refname>setcookie</refname>
    <refpurpose>发送一个 cookie 信息</refpurpose>
   </refnamediv>
   <refsect1>
    <title>描述</title>
     <methodsynopsis>
      <type>boolean</type><methodname>setcookie</methodname>
      <methodparam><type>string</type><parameter>name</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>value</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>expire</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>path</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>domain</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>secure</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>setcookie</function> 函数用来建立一个新的 cookie 的信息。和其它头部信息一样，cookies
     必须要输出在文件的<emphasis>最前面</emphasis>，也就意味着在其之前，你不能输出任何字符
     (这是规定)。包括
     <literal>&lt;html></literal> 和 <literal>&lt;head></literal>
     标签以及一些空格。如果这些标签在使用 <function>setcookie</function> 函数前输出，函数运行则会失败并返回 &false;。
     只要 <function>setcookie</function> 函数成功运行，不管该信息是否被用户接受，都会返回 &true;。
    </para>
    <para>
     除了 <parameter>name</parameter> 以外，其它所有参数都是可选的。如果只有 name
     参数，这将会删除客户端名称为 name
     的 cookie。当然，为了跳过某些参数的设定，你可以为一些参数赋空字符
     (<emphasis>&quot;&quot;</emphasis>)。但参数
     <parameter>expire</parameter> 及
     <parameter>secure</parameter> 的类型应该为整数 (integers) 并且不能被赋为空字符。你可以用 0
     来代替(<emphasis>0</emphasis>)。参数
     <parameter>expire</parameter> 是一个 Unix 的时间戳，可以用
     <function>time</function> 或 <function>mktime</function>
     函数来获得。<parameter>secure</parameter> 参数表明该 cookie
     只在安全 HTTP 连接下才被发送。
    </para>
    <para>
     当 cookies 被设置后，便可以在其它页面通过 <link linkend="reserved.variables.cookies">$_COOKIE</link>
     或 <varname>$HTTP_COOKIE_VARS</varname> 数组取得其值。需要注意的是，<link linkend="language.variables.superglobals">autoglobals</link>
     的 <varname>$_COOKIE</varname> 形式适用于 PHP
     <ulink url="&url.php.release4.1.0;">4.1.0</ulink> 或更高版本。而
     <varname>$HTTP_COOKIE_VARS</varname> 则从 PHP 3 起就可以使用.
    </para>
    <para>
     需要注意的几点:
     <itemizedlist>
      <listitem>
       <simpara>
       Cookies 不会在你设置它的本页生效、要测试一个 cookie 是否被成功的设定，你可以在其到期之前通过另外一个页面来访问其值。过期时间是通过参数
       <parameter>expire</parameter> 来设置的。
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        Cookies 将会被与其同名的后设定的 cookie 所覆盖。
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        在实际运用中，你可以把 Cookies 的名称设置成一个数组，但是数组 cookie 中的每个元素的值将会被单独保存在用户的系统中。你可以试着用<function>explode</function>
        或 <function>serialize</function> 函数来把多个 cookie 值写入到一个 cookie 文件中。
       </simpara>
      </listitem>
     </itemizedlist>
    </para>
    <simpara>
    在 PHP 3 中，在同一个 PHP 脚本中多次使用 <function>setcookie</function>
    来设置 cookie，将会按照倒序的方式来分别执行，如果你想要在插入另外一个 cookie
    前删除一个 cookie,你必须先插入然后再删除。在 PHP 4 里，多次调用
    <function>setcookie</function> 则是按照顺序来执行的。
    </simpara>
    <para>
     下面一些例子说明了如何发送 cookies:
     <example>
      <title><function>setcookie</function> sent examples</title>
      <programlisting role="php">
<![CDATA[
setcookie ("TestCookie", $value);
setcookie ("TestCookie", $value,time()+3600);  /* expire in 1 hour */
setcookie ("TestCookie", $value,time()+3600, "/~rasmus/", ".utoronto.ca", 1);
]]>
      </programlisting>
     </example>
    </para>
    <para>
    一个过期的 cookie 将会被自动删除。例子说明了如何删除一个 cookies:
     <example>
      <title><function>setcookie</function> delete examples</title>
      <programlisting role="php">
<![CDATA[
// set the expiration date to one hour ago
setcookie ("TestCookie", "", time() - 3600);
setcookie ("TestCookie", "", time() - 3600, "/~rasmus/", ".utoronto.ca", 1);
]]>
      </programlisting>
     </example>
    </para>
    <para>
    要注意的是 cookie 的值在发送的时候会被自动的编码并保存，而当你读取它的时候，它又会被自动的解码并自动把自己赋值给与自己同名的一个变量。你可以通过下面简单的例子来看到:
     <informalexample>
      <programlisting role="php">
<![CDATA[
echo $TestCookie;
echo $_COOKIE["TestCookie"];
]]>
      </programlisting>
     </informalexample>
    </para>
    <para>
    你也可以设置一个数组来存放 cookie，把许多名称不同的 cookie 放到一个数组中存放。这样你在接收 cookie
    的时候只需要要获取一个数组:
     <informalexample>
      <programlisting role="php">
<![CDATA[
setcookie ("cookie[three]", "cookiethree");
setcookie ("cookie[two]", "cookietwo");
setcookie ("cookie[one]", "cookieone");
if (isset ($cookie)) {
    while (list ($name, $value) = each ($cookie)) {
        echo "$name == $value<br>\n";
    }
}
]]>
      </programlisting>
     </informalexample>
    </para>
    <para>
    关于 cookies 更多的介绍，可以参考网景公司的 cookies 说明书
    <ulink url="&spec.cookies;">&spec.cookies;</ulink>.
    </para>
    <simpara>
     Netscape Communicator 4.05 及 Microsoft Internet Explorer 3.x 在 cookie 的路径和时间没有设置的情况下会出现一些问题。
    </simpara>
   </refsect1>
  </refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->