avenger Wed Nov 6 23:25:07 2002 EDT
Modified files:
/phpdoc/en/reference/http/functions setcookie.xml
Log:
finished
Index: phpdoc/en/reference/http/functions/setcookie.xml
diff -u phpdoc/en/reference/http/functions/setcookie.xml:1.10
phpdoc/en/reference/http/functions/setcookie.xml:1.11
--- phpdoc/en/reference/http/functions/setcookie.xml:1.10 Wed Nov 6 13:34:39
2002
+++ phpdoc/en/reference/http/functions/setcookie.xml Wed Nov 6 23:25:07 2002
@@ -1,13 +1,13 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.10 $ -->
+<!-- $Revision: 1.11 $ -->
<!-- splitted from ./en/functions/http.xml, last change in rev 1.2 -->
<refentry id="function.setcookie">
<refnamediv>
<refname>setcookie</refname>
- <refpurpose>Send a cookie</refpurpose>
+ <refpurpose>发送一个 cookie 信息</refpurpose>
</refnamediv>
<refsect1>
- <title>Description</title>
+ <title>描述</title>
<methodsynopsis>
<type>boolean</type><methodname>setcookie</methodname>
<methodparam><type>string</type><parameter>name</parameter></methodparam>
@@ -18,81 +18,65 @@
<methodparam
choice="opt"><type>int</type><parameter>secure</parameter></methodparam>
</methodsynopsis>
<para>
- <function>setcookie</function> defines a cookie to be sent along
- with the rest of the HTTP headers. Like other headers, cookies
- must be sent <emphasis>before</emphasis> any output from your
- script (this is a protocol restriction). This requires that you
- place calls to this function prior to any output, including
- <literal><html></literal> and <literal><head></literal> tags
- as well as any whitespace. If output exists prior to calling this
- function, <function>setcookie</function> will fail and return &false;.
- If <function>setcookie</function> successfully runs, it will return
- &true;. This does not indicate whether the user accepted the cookie.
- </para>
- <para>
- All the arguments except the <parameter>name</parameter> argument
- are optional. If only the name argument is present, the cookie
- by that name will be deleted from the remote client. You may
- also replace any argument with an empty string
- (<emphasis>""</emphasis>) in order to skip that
- argument. The <parameter>expire</parameter> and
- <parameter>secure</parameter> arguments are integers and cannot
- be skipped with an empty string. Use a zero
- (<emphasis>0</emphasis>) instead. The
- <parameter>expire</parameter> argument is a regular Unix time
- integer as returned by the <function>time</function> or
- <function>mktime</function> functions. The
- <parameter>secure</parameter> indicates that the cookie should
- only be transmitted over a secure HTTPS connection.
- </para>
- <para>
- Once the cookies have been set, they can be accessed on the next page load
- with the <link linkend="reserved.variables.cookies">$_COOKIE</link> or
- <varname>$HTTP_COOKIE_VARS</varname> arrays. Note,
- <link linkend="language.variables.superglobals">autoglobals</link>
- such as <varname>$_COOKIE</varname> became available in PHP
- <ulink url="&url.php.release4.1.0;">4.1.0</ulink>.
- <varname>$HTTP_COOKIE_VARS</varname> has existed since PHP 3.
+ <function>setcookie</function> 函数用来建立一个新的 cookie
+的信息。和其它头部信息一样，cookies
+
+必须要输出在文件的<emphasis>最前面</emphasis>，也就意味着在其之前，你不能输出任何字符
+ (这是规定)。包括
+ <literal><html></literal> 和 <literal><head></literal>
+ 标签以及一些空格。如果这些标签在使用 <function>setcookie</function>
+函数前输出，函数运行则会失败并返回 &false;。
+ 只要 <function>setcookie</function>
+函数成功运行，不管该信息是否被用户接受，都会返回 &true;。
+ </para>
+ <para>
+ 除了 <parameter>name</parameter> 以外，其它所有参数都是可选的。如果只有 name
+ 参数，这将会删除客户端名称为 name
+ 的 cookie。当然，为了跳过某些参数的设定，你可以为一些参数赋空字符
+ (<emphasis>""</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>
- Common Pitfalls:
+ 需要注意的几点:
<itemizedlist>
<listitem>
<simpara>
- Cookies will not become visible until the next loading of a page that
- the cookie should be visible for. To test if a cookie was successfully
- set, check for the cookie on a next loading page before the cookie
- expires. Expire time is set via the <parameter>expire</parameter>
- parameter.
+ Cookies 不会在你设置它的本页生效、要测试一个 cookie
+是否被成功的设定，你可以在其到期之前通过另外一个页面来访问其值。过期时间是通过参数
+ <parameter>expire</parameter> 来设置的。
</simpara>
</listitem>
<listitem>
<simpara>
- Cookies must be deleted with the same parameters as they were set with.
+ Cookies 将会被与其同名的后设定的 cookie 所覆盖。
</simpara>
</listitem>
<listitem>
<simpara>
- Cookies names can be set as array names and will be available to your
- PHP scripts as arrays but seperate cookies are stored on the users
- system. Consider <function>explode</function> or
- <function>serialize</function> to set one cookie with multiple names
- and values.
+ 在实际运用中，你可以把 Cookies 的名称设置成一个数组，但是数组 cookie
+中的每个元素的值将会被单独保存在用户的系统中。你可以试着用<function>explode</function>
+ 或 <function>serialize</function> 函数来把多个 cookie 值写入到一个 cookie
+文件中。
</simpara>
</listitem>
</itemizedlist>
</para>
<simpara>
- In PHP 3, multiple calls to <function>setcookie</function> in the same
- script will be performed in reverse order. If you are trying to
- delete one cookie before inserting another you should put the
- insert before the delete. In PHP 4, multiple calls to
- <function>setcookie</function> are performed in the order called.
+ 在 PHP 3 中，在同一个 PHP 脚本中多次使用 <function>setcookie</function>
+ 来设置 cookie，将会按照倒序的方式来分别执行，如果你想要在插入另外一个 cookie
+ 前删除一个 cookie,你必须先插入然后再删除。在 PHP 4 里，多次调用
+ <function>setcookie</function> 则是按照顺序来执行的。
</simpara>
<para>
- Some examples follow how to send cookies:
+ 下面一些例子说明了如何发送 cookies:
<example>
- <title><function>setcookie</function> send examples</title>
+ <title><function>setcookie</function> sent examples</title>
<programlisting role="php">
<