setcookie() 定义一个和其余的 HTTP 标头一起发送的
cookie。和其它标头一样,cookie
必须在脚本的任何其它输出之前发送(这是协议限制)。这需要将本函数的调用放到任何输出之前,包括
<html>
和 <head>
标签以及任何空格。如果在调用 setcookie()
之前有任何输出,本函数将失败并返回 FALSE
。如果
setcookie() 函数成功运行,将返回
TRUE
。这并不说明用户是否接受了 cookie。
自 PHP 4
起,可以用输出缓存来在调用本函数前输出内容,代价是把所有向浏览器的输出都缓存在服务器,直到下命令发送它们。可以在代码中使用
ob_start() 及 ob_end_flush()
来实现这样的功能,或者通过修改 php.ini
中的 output_buffering
配置选项来实现,也可以通过修改服务器配置文件来实现。
除了 name 外,其它所有参数都是可选的。可以用空字符串("")替换某参数以跳过该参数。因为参数 expire 是整型,不能用空字符串掉过,可以用零(0)来代替 。下面的表格对 setcookie() 的每一个参数都进行了解释。可以对照 » Netscape cookie 规范以了解 setcookie() 的每一个参数的细节以及通过阅读 » RFC 2965 了解 HTTP cookie 的工作方式。
参数 | 说明 | 举例 |
---|---|---|
name | Cookie 的名字。 |
使用 $_COOKIE['cookiename'] 调用名为 cookiename 的 cookie。
|
value | Cookie 的值。此值保存在客户端,不要用来保存敏感数据。 |
假定 name 是 'cookiename',可以通过
$_COOKIE['cookiename'] 取得其值。
|
expire | Cookie 过期的时间。这是个 Unix 时间戳,即从 Unix 纪元开始的秒数。换而言之,通常用 time() 函数再加上秒数来设定 cookie 的失效期。或者用 mktime()来实现。 |
time()+60*60*24*30 将设定 cookie
30 天后失效。如果未设定,cookie
将会在会话结束后(一般是浏览器关闭)失效。
|
path | Cookie 在服务器端的有效路径。 |
如果该参数设为 '/' 的话,cookie 就在整个
domain 内有效,如果设为
'/foo/' ,cookie
就只在 domain 下的
/foo/ 目录及其子目录内有效,例如
/foo/bar/ 。默认值为设定 cookie 的当前目录。
|
domain | 该 cookie 有效的域名。 |
要使 cookie 能在如 example.com 域名下的所有子域都有效的话,该参数应该设为
'.example.com' 。虽然 .
并不必须的,但加上它会兼容更多的浏览器。如果该参数设为
www.example.com 的话,就只在
www 子域内有效。细节见
» Cookie 规范中的 tail matching。
|
secure |
指明 cookie 是否仅通过安全的 HTTPS 连接传送。当设成 TRUE
时,cookie 仅在安全的连接中被设置。默认值为 FALSE 。
|
0 或 1
|
当 cookie 被设置后,便可以在其它页面通过 $_COOKIE
或 $HTTP_COOKIE_VARS
数组取得其值。需要注意的是,autoglobals
的 $_COOKIE
形式适用于 PHP
» 4.1.0 或更高版本。而
$HTTP_COOKIE_VARS
则从 PHP 3 起就可以使用。Cookie
的值也会被保存到 $_REQUEST 数组中。
如果 PHP 的选项 register_globals
被设为 on
的话,cookie
的值仍然会被斌到变量内。在下面的例子中,$TestCookie
会被注册,但是仍然推荐使用 $_COOKIE
数组。
常见缺陷:
print_r($_COOKIE);
来调试现有的 cookies。
FALSE
,并且其它的参数都和前一次调用 setcookie 时相同,那么所指定名称的
cookie 将会在远程客户端被删除。
FALSE
会使客户端尝试删除这个 cookie,所以要在 cookie
上保存 TRUE
或 FALSE
时不应该直接使用 boolean 值,而应该用 0
来表示 FALSE
,用 1 来表示 TRUE
在 PHP 3 中,在同一个 PHP 脚本中多次使用 setcookie() 来设置 cookie,将会按照倒序的方式来分别执行,如果想要在插入另外一个 cookie 之前删除一个 cookie,要把插入放到删除之前。自 PHP 4 起,多次调用 setcookie() 则是按照顺序来执行的。
下面一些例子说明了如何发送 cookie:
$value = 'something from somewhere';
setcookie("TestCookie", $value);
setcookie("TestCookie", $value,time()+3600); /* expire in 1 hour */
setcookie("TestCookie", $value,time()+3600, "/~rasmus/", ".utoronto.ca", 1); ?>
注意 cookie 中值的部分在发送的时候会被自动用 urlencode 编码并在接收到的时候被自动解码并把值赋给与自己同名的 cookie 变量。如果不想这样并且在使用 PHP 5 的话,可以用 setrawcookie() 来代替。下面这个简单的例子可以得到刚才所设定的 cookie 的值:
<?php
// 输出单独的 cookie
echo $_COOKIE["TestCookie"];
echo $HTTP_COOKIE_VARS["TestCookie"];
// 另一个调试的方法就是输出所有的 cookie
print_r($_COOKIE);
?>
要删除 cookie 需要确保它的失效期是在过去,才能触发浏览器的删除机制。下面的例子说明了如何删除刚才设置的 cookie:
// 将过期时间设为一小时前
setcookie("TestCookie", "", time() - 3600);
setcookie("TestCookie", "", time() - 3600, "/~rasmus/", ".utoronto.ca", 1); ?>
也可以通过在 cookie 名称中使用数组符号来设定数组 cookie,可以设定多个 cookie 作为数组单元,在脚本提取 cookie 时所有的值都放在一个数组种:
<?php
// 设定 cookie
setcookie("cookie[three]", "cookiethree");
setcookie("cookie[two]", "cookietwo");
setcookie("cookie[one]", "cookieone");
// 刷新页面后,显示出来
if (isset($_COOKIE['cookie'])) {
foreach ($_COOKIE['cookie'] as $name => $value) {
echo "$name : $value <br />\n";
}
}
?>
上例将输出:
three : cookiethree
two : cookietwo
one : cookieone
下面的一些 RFC 也具参考价值:» RFC 2109 和 » RFC 2695。
注意 expire 参数的接受的是 Unix
时间戳,而不是日期格式
Wdy, DD-Mon-YYYY HH:MM:SS GMT
,这是因为 PHP
在内部进行了转换。
expire 是与客户端的时间相比较,和服务器时间可能不同。
向 Microsoft Internet Explorer 4 Service Pack 1 不能正确处理设定了 path 的 cookie。
Netscape Communicator 4.05 及 Microsoft Internet Explorer 3.x 不能正确处理没有设定 path 和 time 的 cookie。
参见 header(),setrawcookie() 和本手册中的 cookie 一章。