setcookie

說明

bool setcookie ( string name [, string value [, int expire [, string path [, string domain [, bool secure]]]]] )

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 的工作模式。

表格 1. setcookie() 參數詳解

參數	說明	舉例
`name`	Cookie 的名字。	使用 `$_COOKIE['cookiename']` 呼叫名為 cookiename 的 cookie。
`value`	Cookie 的值。此值儲存在用戶端，不要用來儲存敏感資料。	假定 `name` 是 'cookiename'，可以通過 `$_COOKIE['cookiename']` 取得其值。
`expire`	Cookie 過期的時間。這是個 Unix 時間戳，即從 Unix 紀元開始的秒數。換而言之，通常用 time() 函數再加上秒數來設定 cookie 的失效期。或是用 mktime()來實現。	`time()+606024*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 陣列。

常見缺陷：

Cookies 不會在設定它的本頁生效，要測試一個 cookie 是否被成功的設定，可以在其到期之前通過另外一個頁面來訪問其值。過期時間是通過參數 expire 來設定的。可以簡單地使用 print_r($_COOKIE); 來除錯現有的 cookies。
Cookie 必須用和設定時的同樣的參數才能移除。若果其值一個空字串，或是是 FALSE，並且其它的參數都和前一次呼叫 setcookie 時相同，那麼所指定名稱的 cookie 將會在遠端用戶端被移除。
由於把 cookie 的值設為 FALSE 會使用戶端嘗試移除這個 cookie，所以要在 cookie 上儲存 TRUE 或 FALSE 時不應該直接使用 boolean 值，而應該用 0 來表示 FALSE，用 1 來表示 TRUE
可以把 cookie 的名稱設定成一個陣列，但是陣列 cookie 中的每個元素的值將會被單獨儲存在會員的系統中。考慮使用 explode() 函數用多個名稱和值設定一個 cookie。不推薦將 serialize() 用於此目的，因為它可能會導致一個安全漏洞。

在 PHP 3 中，在同一個 PHP 腳本中多次使用 setcookie() 來設定 cookie，將會按照倒序的模式來分別執行，若果想要在插入另外一個 cookie 之前移除一個 cookie，要把插入放到移除之前。自 PHP 4 起，多次呼叫 setcookie() 則是按照順序來執行的。

下面一些例子說明了如何傳送 cookie：
例子 1. setcookie() 傳送例子
$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：
例子 2. setcookie() 移除例子
// 將過期時間設為一小時前 setcookie("TestCookie", "", time() - 3600); setcookie("TestCookie", "", time() - 3600, "/~rasmus/", ".utoronto.ca", 1);

也可以通過在 cookie 名稱中使用陣列符號來設定陣列 cookie，可以設定多個 cookie 作為陣列單元，在腳本提取 cookie 時所有的值都放在一個陣列種：

例子 3. setcookie() 中使用陣列的例子
<?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 一章。