<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>setcookie</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REL="HOME"
TITLE="PHP 手册"
HREF="index.html"><LINK
REL="UP"
TITLE="Network Functions"
HREF="ref.network.html"><LINK
REL="PREVIOUS"
TITLE="pfsockopen"
HREF="function.pfsockopen.html"><LINK
REL="NEXT"
TITLE="setrawcookie"
HREF="function.setrawcookie.html"><META
HTTP-EQUIV="Content-type"
CONTENT="text/html; charset=UTF-8"></HEAD
><BODY
CLASS="refentry"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>PHP 手册</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="function.pfsockopen.html"
ACCESSKEY="P"
>上一页</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="function.setrawcookie.html"
ACCESSKEY="N"
>下一页</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><H1
><A
NAME="function.setcookie"
></A
>setcookie</H1
><DIV
CLASS="refnamediv"
><A
NAME="AEN149731"
></A
><P
> (PHP 3, PHP 4, PHP 5)</P
>setcookie -- Send a cookie</DIV
><DIV
CLASS="refsect1"
><A
NAME="AEN149734"
></A
><H2
>Description</H2
>bool <B
CLASS="methodname"
>setcookie</B
> ( string name [, string value [, int expire [, string path [, string domain [, bool secure [, bool httponly]]]]]] )<BR
></BR
><P
> <B
CLASS="function"
>setcookie()</B
> defines a cookie to be sent along
with the rest of the HTTP headers. Like other headers, cookies
must be sent <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>before</I
></SPAN
> any output from your
script (this is a protocol restriction). This requires that you
place calls to this function prior to any output, including
<TT
CLASS="literal"
><html></TT
> and <TT
CLASS="literal"
><head></TT
> tags
as well as any whitespace. If output exists prior to calling this
function, <B
CLASS="function"
>setcookie()</B
> will fail and return <TT
CLASS="constant"
><B
>FALSE</B
></TT
>.
If <B
CLASS="function"
>setcookie()</B
> successfully runs, it will return
<TT
CLASS="constant"
><B
>TRUE</B
></TT
>. This does not indicate whether the user accepted the cookie.
</P
><DIV
CLASS="note"
><BLOCKQUOTE
CLASS="note"
><P
><B
>注意: </B
>
As of PHP 4, you can use output buffering to send output prior to the
call of this function, with the overhead of all of your output to the
browser being buffered in the server until you send it. You can do this
by calling <A
HREF="function.ob-start.html"
><B
CLASS="function"
>ob_start()</B
></A
> and
<A
HREF="function.ob-end-flush.html"
><B
CLASS="function"
>ob_end_flush()</B
></A
> in your script, or setting the
<TT
CLASS="literal"
>output_buffering</TT
> configuration directive on in your
<TT
CLASS="filename"
>php.ini</TT
> or server configuration files.
</P
></BLOCKQUOTE
></DIV
><P
> All the arguments except the <CODE
CLASS="parameter"
>name</CODE
> argument
are optional. You may also replace an argument with an empty string
(<SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>""</I
></SPAN
>) in order to skip that
argument. Because the <CODE
CLASS="parameter"
>expire</CODE
>
argument is integer, it cannot
be skipped with an empty string, use a zero (<SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>0</I
></SPAN
>)
instead. The following table explains each parameter of the
<B
CLASS="function"
>setcookie()</B
> function, be sure to read the
<A
HREF="http://wp.netscape.com/newsref/std/cookie_spec.html"
TARGET="_top"
>Netscape cookie specification</A
> for
specifics on how each <B
CLASS="function"
>setcookie()</B
> parameter works
and <A
HREF="http://www.faqs.org/rfcs/rfc2965"
TARGET="_top"
>RFC 2965</A
> for additional
information on how HTTP cookies work.
</P
><P
> <DIV
CLASS="table"
><A
NAME="AEN149785"
></A
><P
><B
>表 1. <B
CLASS="function"
>setcookie()</B
> parameters explained</B
></P
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><COL><COL><COL><THEAD
><TR
><TH
>Parameter</TH
><TH
>Description</TH
><TH
>Examples</TH
></TR
></THEAD
><TBODY
><TR
><TD
><CODE
CLASS="parameter"
>name</CODE
></TD
><TD
> The name of the cookie.
</TD
><TD
> 'cookiename' is called as <CODE
CLASS="varname"
>$_COOKIE['cookiename']</CODE
>
</TD
></TR
><TR
><TD
><CODE
CLASS="parameter"
>value</CODE
></TD
><TD
> The value of the cookie. This value is stored on the clients
computer; do not store sensitive information.
</TD
><TD
> Assuming the <CODE
CLASS="parameter"
>name</CODE
> is 'cookiename', this
value is retrieved through <CODE
CLASS="varname"
>$_COOKIE['cookiename']</CODE
>
</TD
></TR
><TR
><TD
><CODE
CLASS="parameter"
>expire</CODE
></TD
><TD
> The time the cookie expires. This is a Unix timestamp so is
in number of seconds since the epoch. In other words, you'll
most likely set this with the <A
HREF="function.time.html"
><B
CLASS="function"
>time()</B
></A
> function
plus the number of seconds before you want it to expire. Or
you might use <A
HREF="function.mktime.html"
><B
CLASS="function"
>mktime()</B
></A
>.
</TD
><TD
> <TT
CLASS="literal"
>time()+60*60*24*30</TT
> will set the cookie to
expire in 30 days. If set to 0, or omitted, the cookie will expire at
the end of the session (when the browser closes).
</TD
></TR
><TR
><TD
><CODE
CLASS="parameter"
>path</CODE
></TD
><TD
> The path on the server in which the cookie will be available on.
</TD
><TD
> If set to <TT
CLASS="literal"
>'/'</TT
>, the cookie will be available
within the entire <CODE
CLASS="parameter"
>domain</CODE
>. If set to
<TT
CLASS="literal"
>'/foo/'</TT
>, the cookie will only be available
within the <TT
CLASS="literal"
>/foo/</TT
> directory and all
sub-directories such as <TT
CLASS="literal"
>/foo/bar/</TT
> of
<CODE
CLASS="parameter"
>domain</CODE
>. The default value is the
current directory that the cookie is being set in.
</TD
></TR
><TR
><TD
><CODE
CLASS="parameter"
>domain</CODE
></TD
><TD
> The domain that the cookie is available.
</TD
><TD
> To make the cookie available on all subdomains of example.com
then you'd set it to <TT
CLASS="literal"
>'.example.com'</TT
>. The
<TT
CLASS="literal"
>.</TT
> is not required but makes it compatible
with more browsers. Setting it to <TT
CLASS="literal"
>www.example.com</TT
>
will make the cookie only available in the <TT
CLASS="literal"
>www</TT
>
subdomain. Refer to tail matching in the
<A
HREF="http://wp.netscape.com/newsref/std/cookie_spec.html"
TARGET="_top"
>spec</A
> for details.
</TD
></TR
><TR
><TD
><CODE
CLASS="parameter"
>secure</CODE
></TD
><TD
> Indicates that the cookie should only be transmitted over a
secure HTTPS connection from the client. When set to <TT
CLASS="constant"
><B
>TRUE</B
></TT
>, the
cookie will only be set if a secure connection exists. The default
is <TT
CLASS="constant"
><B
>FALSE</B
></TT
>. On the server-side, it's on the programmer to send this
kind of cookie only on secure connection (e.g. with respect to
<TT
CLASS="literal"
>$_SERVER["HTTPS"]</TT
>).
</TD
><TD
> <TT
CLASS="constant"
><B
>TRUE</B
></TT
> or <TT
CLASS="constant"
><B
>FALSE</B
></TT
>
</TD
></TR
><TR
><TD
><CODE
CLASS="parameter"
>httponly</CODE
></TD
><TD
> When <TT
CLASS="constant"
><B
>TRUE</B
></TT
> the cookie will be made accessible only through the HTTP
protocol. This means that the cookie won't be accessible by
scripting languages, such as JavaScript. This setting can effectly
help to reduce identity theft through XSS attacks (although it is
not supported by all browsers). Added in PHP 5.2.0.
</TD
><TD
> <TT
CLASS="constant"
><B
>TRUE</B
></TT
> or <TT
CLASS="constant"
><B
>FALSE</B
></TT
>
</TD
></TR
></TBODY
></TABLE
></DIV
>
</P
><P
> Once the cookies have been set, they can be accessed on the next page load
with the <A
HREF="reserved.variables.html#reserved.variables.cookies"
>$_COOKIE</A
> or
<CODE
CLASS="varname"
>$HTTP_COOKIE_VARS</CODE
> arrays. Note,
<A
HREF="language.variables.predefined.html#language.variables.superglobals"
>superglobals</A
>
such as <CODE
CLASS="varname"
>$_COOKIE</CODE
> became available in PHP
<A
HREF="http://www.php.net/releases/4_1_0.php"
TARGET="_top"
>4.1.0</A
>.
<CODE
CLASS="varname"
>$HTTP_COOKIE_VARS</CODE
> has existed since PHP 3. Cookie
values also exist in <A
HREF="reserved.variables.html#reserved.variables.request"
> $_REQUEST</A
>.
</P
><DIV
CLASS="note"
><BLOCKQUOTE
CLASS="note"
><P
><B
>注意: </B
>
If the PHP directive <A
HREF="ini.core.html#ini.register-globals"
>register_globals</A
>
is set to <TT
CLASS="literal"
>on</TT
> then cookie values will also be made into
variables. In our examples below, <CODE
CLASS="varname"
>$TestCookie</CODE
> will
exist. It's recommended to use <CODE
CLASS="varname"
>$_COOKIE</CODE
>.
</P
></BLOCKQUOTE
></DIV
><P
> Common Pitfalls:
<P
></P
><UL
><LI
><P
> 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 <CODE
CLASS="parameter"
>expire</CODE
>
parameter. A nice way to debug the existence of cookies is by
simply calling <TT
CLASS="literal"
>print_r($_COOKIE);</TT
>.
</P
></LI
><LI
><P
> Cookies must be deleted with the same parameters as they were set with.
If the value argument is an empty string, or <TT
CLASS="constant"
><B
>FALSE</B
></TT
>, and all other arguments
match a previous call to setcookie, then the cookie with the specified
name will be deleted from the remote client.
</P
></LI
><LI
><P
> Because setting a cookie with a value of <TT
CLASS="constant"
><B
>FALSE</B
></TT
> will try to delete the cookie,
you should not use boolean values. Instead, use <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>0</I
></SPAN
> for <TT
CLASS="constant"
><B
>FALSE</B
></TT
>
and <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>1</I
></SPAN
> for <TT
CLASS="constant"
><B
>TRUE</B
></TT
>.
</P
></LI
><LI
><P
> Cookies names can be set as array names and will be available to your
PHP scripts as arrays but separate cookies are stored on the users
system. Consider <A
HREF="function.explode.html"
><B
CLASS="function"
>explode()</B
></A
> to set one cookie with
multiple names and values. It is not recommended to use
<A
HREF="function.serialize.html"
><B
CLASS="function"
>serialize()</B
></A
> for this purpose, because it can result
in security holes.
</P
></LI
></UL
>
</P
><P
> In PHP 3, multiple calls to <B
CLASS="function"
>setcookie()</B
> 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. As of PHP 4, multiple calls to
<B
CLASS="function"
>setcookie()</B
> are performed in the order called.
</P
><P
> Some examples follow how to send cookies:
<TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
CLASS="EXAMPLE"
><TR
><TD
><DIV
CLASS="example"
><A
NAME="AEN149893"
></A
><P
><B
>例 1. <B
CLASS="function"
>setcookie()</B
> send example</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><code><font color="#000000">
<font color="#0000BB"><?php<br />$value </font><font color="#007700">= </font><font color="#DD0000">'something from somewhere'</font><font color="#007700">;<br /><br /></font><font color="#0000BB">setcookie</font><font color="#007700">(</font><font color="#DD0000">"TestCookie"</font><font color="#007700">, </font><font color="#0000BB">$value</font><font color="#007700">);<br /></font><font color="#0000BB">setcookie</font><font color="#007700">(</font><font color="#DD0000">"TestCookie"</font><font color="#007700">, </font><font color="#0000BB">$value</font><font color="#007700">, </font><font color="#0000BB">time</font><font color="#007700">()+</font><font color="#0000BB">3600</font><font color="#007700">); </font><font color="#FF8000">/* expire in 1 hour */<br /></font><font color="#0000BB">setcookie</font><font color="#007700">(</font><font color="#DD0000">"TestCookie"</font><font color="#007700">, </font><font color="#0000BB">$value</font><font color="#007700">, </font><font color="#0000BB">time</font><font color="#007700">()+</font><font color="#0000BB">3600</font><font color="#007700">, </font><font color="#DD0000">"/~rasmus/"</font><font color="#007700">, </font><font color="#DD0000">".example.com"</font><font color="#007700">, </font><font color="#0000BB">1</font><font color="#007700">);<br /></font><font color="#0000BB">?></font>
</font>
</code></TD
></TR
></TABLE
></DIV
></TD
></TR
></TABLE
>
</P
><P
> Note that the value portion of the cookie will automatically be
urlencoded when you send the cookie, and when it is received, it
is automatically decoded and assigned to a variable by the same
name as the cookie name. If you don't want this, you can use
<A
HREF="function.setrawcookie.html"
><B
CLASS="function"
>setrawcookie()</B
></A
> instead if you are using PHP 5. To see
the contents of our test cookie in a script, simply use one of the
following examples:
</P
><P
> <DIV
CLASS="informalexample"
><P
></P
><A
NAME="AEN149900"
></A
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><code><font color="#000000">
<font color="#0000BB"><?php<br /></font><font color="#FF8000">// Print an individual cookie<br /></font><font color="#007700">echo </font><font color="#0000BB">$_COOKIE</font><font color="#007700">[</font><font color="#DD0000">"TestCookie"</font><font color="#007700">];<br />echo </font><font color="#0000BB">$HTTP_COOKIE_VARS</font><font color="#007700">[</font><font color="#DD0000">"TestCookie"</font><font color="#007700">];<br /><br /></font><font color="#FF8000">// Another way to debug/test is to view all cookies<br /></font><font color="#0000BB">print_r</font><font color="#007700">(</font><font color="#0000BB">$_COOKIE</font><font color="#007700">);<br /></font><font color="#0000BB">?></font>
</font>
</code></TD
></TR
></TABLE
><P
></P
></DIV
>
</P
><P
> When deleting a cookie you should assure that the expiration date
is in the past, to trigger the removal mechanism in your browser.
Examples follow how to delete cookies sent in previous example:
</P
><P
> <TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
CLASS="EXAMPLE"
><TR
><TD
><DIV
CLASS="example"
><A
NAME="AEN149904"
></A
><P
><B
>例 2. <B
CLASS="function"
>setcookie()</B
> delete example</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><code><font color="#000000">
<font color="#0000BB"><?php<br /></font><font color="#FF8000">// set the expiration date to one hour ago<br /></font><font color="#0000BB">setcookie </font><font color="#007700">(</font><font color="#DD0000">"TestCookie"</font><font color="#007700">, </font><font color="#DD0000">""</font><font color="#007700">, </font><font color="#0000BB">time</font><font color="#007700">() - </font><font color="#0000BB">3600</font><font color="#007700">);<br /></font><font color="#0000BB">setcookie </font><font color="#007700">(</font><font color="#DD0000">"TestCookie"</font><font color="#007700">, </font><font color="#DD0000">""</font><font color="#007700">, </font><font color="#0000BB">time</font><font color="#007700">() - </font><font color="#0000BB">3600</font><font color="#007700">, </font><font color="#DD0000">"/~rasmus/"</font><font color="#007700">, </font><font color="#DD0000">".example.com"</font><font color="#007700">, </font><font color="#0000BB">1</font><font color="#007700">);<br /></font><font color="#0000BB">?></font>
</font>
</code></TD
></TR
></TABLE
></DIV
></TD
></TR
></TABLE
>
</P
><P
> You may also set array cookies by using array notation in the
cookie name. This has the effect of setting as many cookies as
you have array elements, but when the cookie is received by your
script, the values are all placed in an array with the cookie's
name:
</P
><P
> <TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
CLASS="EXAMPLE"
><TR
><TD
><DIV
CLASS="example"
><A
NAME="AEN149910"
></A
><P
><B
>例 3. <B
CLASS="function"
>setcookie()</B
> and arrays</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><code><font color="#000000">
<font color="#0000BB"><?php<br /></font><font color="#FF8000">// set the cookies<br /></font><font color="#0000BB">setcookie</font><font color="#007700">(</font><font color="#DD0000">"cookie[three]"</font><font color="#007700">, </font><font color="#DD0000">"cookiethree"</font><font color="#007700">);<br /></font><font color="#0000BB">setcookie</font><font color="#007700">(</font><font color="#DD0000">"cookie[two]"</font><font color="#007700">, </font><font color="#DD0000">"cookietwo"</font><font color="#007700">);<br /></font><font color="#0000BB">setcookie</font><font color="#007700">(</font><font color="#DD0000">"cookie[one]"</font><font color="#007700">, </font><font color="#DD0000">"cookieone"</font><font color="#007700">);<br /><br /></font><font color="#FF8000">// after the page reloads, print them out<br /></font><font color="#007700">if (isset(</font><font color="#0000BB">$_COOKIE</font><font color="#007700">[</font><font color="#DD0000">'cookie'</font><font color="#007700">])) {<br /> foreach (</font><font color="#0000BB">$_COOKIE</font><font color="#007700">[</font><font color="#DD0000">'cookie'</font><font color="#007700">] as </font><font color="#0000BB">$name </font><font color="#007700">=> </font><font color="#0000BB">$value</font><font color="#007700">) {<br /> echo </font><font color="#DD0000">"$name : $value <br /></font><font color="#007700">\n</font><font color="#DD0000">"</font><font color="#007700">;<br /> }<br />}<br /></font><font color="#0000BB">?></font>
</font>
</code></TD
></TR
></TABLE
><P
> which prints
</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="screen"
>three : cookiethree
two : cookietwo
one : cookieone</PRE
></TD
></TR
></TABLE
></DIV
></TD
></TR
></TABLE
>
</P
><DIV
CLASS="note"
><BLOCKQUOTE
CLASS="note"
><P
><B
>注意: </B
>
The following RFC's may also be useful:
<A
HREF="http://www.faqs.org/rfcs/rfc2109"
TARGET="_top"
>RFC 2109</A
> and
<A
HREF="http://www.faqs.org/rfcs/rfc2965"
TARGET="_top"
>RFC 2695</A
>
</P
><P
> You may notice the <CODE
CLASS="parameter"
>expire</CODE
> parameter takes on a
Unix timestamp, as opposed to the date format <TT
CLASS="literal"
>Wdy, DD-Mon-YYYY
HH:MM:SS GMT</TT
>, this is because PHP does this conversion
internally.
</P
><P
> <CODE
CLASS="parameter"
>expire</CODE
> is compared to the client's time which can
differ from server's time.
</P
></BLOCKQUOTE
></DIV
><DIV
CLASS="note"
><BLOCKQUOTE
CLASS="note"
><P
><B
>注意: </B
>
Microsoft Internet Explorer 4 with Service Pack 1 applied does
not correctly deal with cookies that have their path parameter
set.
</P
><P
> Netscape Communicator 4.05 and Microsoft Internet Explorer 3.x
appear to handle cookies incorrectly when the path and time
are not set.
</P
></BLOCKQUOTE
></DIV
><P
> See also <A
HREF="function.header.html"
><B
CLASS="function"
>header()</B
></A
>, <A
HREF="function.setrawcookie.html"
><B
CLASS="function"
>setrawcookie()</B
></A
>
and the <A
HREF="features.cookies.html"
>cookies section</A
>.
</P
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="function.pfsockopen.html"
ACCESSKEY="P"
>上一页</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>起始页</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="function.setrawcookie.html"
ACCESSKEY="N"
>下一页</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>pfsockopen</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="ref.network.html"
ACCESSKEY="U"
>上一级</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>setrawcookie</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
