萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> PHP 程式設計

PHP setcookie() 完整指南:參數詳解、陣列儲存與安全屬性

前言

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

參數詳細說明

參數型別說明關鍵點
namestringCookie 名稱不可包含分號、逗號、空白、等號;建議 ASCII 字元
valuestringCookie 值自動 urlencode;陣列/物件需先 serialize/json_encode
expiresint過期 Unix 時間戳0 或省略 = Session Cookie(瀏覽器關閉失效);必須設定 否則不生效
pathstring生效路徑預設為當前腳本目錄;建議 '/' 全站有效
domainstring生效域名'.example.com' 含子域名;'' 僅當前主機;不可跨主域
securebool僅 HTTPS 傳輸生產環境必開 true
httponlybool禁止 JS 存取防 XSS 必開 true
samesitestringSameSite 屬性(PHP 7.3+ 陣列語法)'Lax'(預設)、'Strict'、'None'(需 secure=true)

基本操作範例

設定 Cookie(傳統語法)

<?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'
]);
?>

讀取 Cookie

<?php
// 直接存取超全域陣列
$value = $_COOKIE['TestCookie'] ?? '未設定';

// 刪除 Cookie:設定過期時間為過去
setcookie('TestCookie', '', time() - 3600, '/');
?>

進階技巧:儲存陣列/物件

Cookie 只能儲存字串,需序列化:

方法一:serialize() + base64_encode()(PHP 原生)

<?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() 有反序列化漏洞風險(若資料被竄改),不建議用於不可信資料。

方法二:json_encode()(推薦,跨語言、安全)

<?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)、整數鍵會變字串。

常見坑點與解決

1. Cookie 不生效?檢查清單

  • ❌ setcookie() 在 <html>、echo、空白行、BOM 之後呼叫
  • ❌ expires 為 0 或未設定(成 Session Cookie),但瀏覽器關閉即失效
  • ❌ path 設定錯誤(如 /admin 導致前台讀不到)
  • ❌ domain 設定錯誤(如 example.com 無前綴點,子域名無法共享)
  • ❌ secure=true 但在 HTTP 環境測試
  • ❌ 瀏覽器禁用 Cookie / 隱私模式 / 防追蹤開啟

2. 中文亂碼

Cookie 值自動 urlencode,讀取時 PHP 自動 urldecode,通常無需手動處理。若手動編碼導致雙重編碼,請檢查邏輯。

3. 同名 Cookie 衝突

同名 Cookie 以 path、domain 最精確者優先。避免在不同路徑/域名設定同名 Cookie。

安全最佳實踐清單

  1. 敏感資料不存 Cookie:Token、用戶 ID、權限資訊放 Session/資料庫,Cookie 只存加密簽名的識別碼。
  2. 啟用 HttpOnly:防止 XSS 竊取 document.cookie。
  3. 啟用 Secure:僅 HTTPS 傳輸,防中間人攻擊。
  4. 設定 SameSite:Lax 平衡安全與體驗;關鍵操作(登入、支付)用 Strict;跨站需求用 None(必須 Secure)。
  5. 簽名驗證:hash_hmac('sha256', $value, $secret) 防竄改。
  6. 加密儲存:極敏感資料(極少見)用 openssl_encrypt()。

結語

setcookie() 看似簡單,實則涉及 HTTP 協議、瀏覽器行為、安全模型多層面。掌握參數細節、善用 JSON 序列化、落實安全屬性,才能讓 Cookie 成為可靠的狀態管理工具,而非安全漏洞溫床。

copyright © 萬盛學電腦網 all rights reserved