setcookie() 是 PHP 發送 HTTP Cookie 的核心函數。雖然語法簡單,但參數細節(特別是路徑、域名、安全屬性)直接影響 Cookie 的可用性與安全性。本文完整解析所有參數、陣列序列化儲存、常見坑點與現代安全最佳實踐。
setcookie(
string $name,
string $value = "",
int $expires_or_options = 0,
string $path = "",
string $domain = "",
bool $secure = false,
bool $httponly = false
): bool
// PHP 7.3+ 替代語法:$expires_or_options 可為陣列
setcookie(string $name, string $value = "", array $options = []): bool
| 參數 | 型別 | 說明 | 關鍵點 |
|---|---|---|---|
| name | string | Cookie 名稱 | 不可包含分號、逗號、空白、等號;建議 ASCII 字元 |
| value | string | Cookie 值 | 自動 urlencode;陣列/物件需先 serialize/json_encode |
| expires | int | 過期 Unix 時間戳 | 0 或省略 = Session Cookie(瀏覽器關閉失效);必須設定 否則不生效 |
| path | string | 生效路徑 | 預設為當前腳本目錄;建議 '/' 全站有效 |
| domain | string | 生效域名 | '.example.com' 含子域名;'' 僅當前主機;不可跨主域 |
| secure | bool | 僅 HTTPS 傳輸 | 生產環境必開 true |
| httponly | bool | 禁止 JS 存取 | 防 XSS 必開 true |
| samesite | string | SameSite 屬性(PHP 7.3+ 陣列語法) | 'Lax'(預設)、'Strict'、'None'(需 secure=true) |
<?php
// 必須在任何輸出前(含空白、BOM)
$value = 'my cookie value';
// 24 小時後過期,全站有效
setcookie('TestCookie', $value, time() + 86400, '/');
// 僅 HTTPS、HttpOnly、SameSite=Lax(需 PHP 7.3+ 陣列語法)
setcookie('SecureCookie', 'secret', [
'expires' => time() + 86400,
'path' => '/',
'domain' => '',
'secure' => true,
'httponly' => true,
'samesite' => 'Lax'
]);
?>
<?php
// 直接存取超全域陣列
$value = $_COOKIE['TestCookie'] ?? '未設定';
// 刪除 Cookie:設定過期時間為過去
setcookie('TestCookie', '', time() - 3600, '/');
?>
Cookie 只能儲存字串,需序列化:
<?php
// a.php 寫入
$cart = [
['id' => 1, 'name' => '商品A', 'qty' => 2],
['id' => 2, 'name' => '商品B', 'qty' => 1],
];
$encoded = base64_encode(serialize($cart));
setcookie('cart', $encoded, time() + 86400, '/', '', true, true);
// b.php 讀取
if (isset($_COOKIE['cart'])) {
$cart = unserialize(base64_decode($_COOKIE['cart']));
print_r($cart);
}
?>
優點:保留 PHP 型別(整數、布林、null)。
缺點:unserialize() 有反序列化漏洞風險(若資料被竄改),不建議用於不可信資料。
<?php
// 寫入
$cart = [['id'=>1, 'name'=> '商品A', 'qty'=>2]];
setcookie('cart', json_encode($cart), time() + 86400, '/', '', true, true);
// 讀取
$cart = json_decode($_COOKIE['cart'] ?? '[]', true); // true = 關聯陣列
print_r($cart);
?>
優點:安全、跨語言、可讀、無反序列化風險。
缺點:不支援 resource、物件(需實作 JsonSerializable)、整數鍵會變字串。
setcookie() 在 <html>、echo、空白行、BOM 之後呼叫expires 為 0 或未設定(成 Session Cookie),但瀏覽器關閉即失效path 設定錯誤(如 /admin 導致前台讀不到)domain 設定錯誤(如 example.com 無前綴點,子域名無法共享)secure=true 但在 HTTP 環境測試Cookie 值自動 urlencode,讀取時 PHP 自動 urldecode,通常無需手動處理。若手動編碼導致雙重編碼,請檢查邏輯。
同名 Cookie 以 path、domain 最精確者優先。避免在不同路徑/域名設定同名 Cookie。
document.cookie。Lax 平衡安全與體驗;關鍵操作(登入、支付)用 Strict;跨站需求用 None(必須 Secure)。hash_hmac('sha256', $value, $secret) 防竄改。openssl_encrypt()。setcookie() 看似簡單,實則涉及 HTTP 協議、瀏覽器行為、安全模型多層面。掌握參數細節、善用 JSON 序列化、落實安全屬性,才能讓 Cookie 成為可靠的狀態管理工具,而非安全漏洞溫床。