PHP setcookie() 完整參數詳解與最佳實踐

基本規則：必須在輸出前呼叫

setcookie() 定義的 Cookie 必須隨 HTTP 標頭一起送出，因此必須在任何輸出（HTML、空白、echo 等）之前呼叫。若在此之前有任何輸出，函式將失敗回傳 false；成功則回傳 true（不代表瀏覽器一定接受）。

函式簽名

bool setcookie(
    string $name,
    string $value = "",
    int $expire = 0,
    string $path = "",
    string $domain = "",
    bool $secure = false,
    bool $httponly = false
)

註：PHP 5.2+ 新增 httponly 參數，防止 JavaScript 存取，提升安全性。

參數詳細說明

name（Cookie 名稱）

透過 $_COOKIE['name'] 讀取。命名建議：僅用英數字、底線，避免特殊字元。

value（Cookie 值）

儲存在客戶端，**切勿存放敏感資料**（密碼、Token 等）。值會自動 urlencode，讀取時自動解碼。若不想編碼，PHP 5.5+ 可用 setrawcookie()。

expire（過期時間，Unix 時間戳）

• 常用寫法：time() + 3600（1小時）、time() + 86400 * 30（30天）。
• 設為 0 或省略：瀏覽器關閉即失效（Session Cookie）。
• 設為過去時間：刪除 Cookie（見下文範例）。

path（生效路徑）

• /：整個網域有效（推薦）。
• /foo/：僅 /foo/ 及子目錄有效。
• 預設：執行腳本所在目錄。

domain（生效網域）

• .example.com：example.com 及所有子網域有效（前綴點可省略但建議加上）。
• www.example.com：僅 www 子網域有效。
• 預設：當前網域（不含子網域）。

secure（僅 HTTPS 傳輸）

設 true 時，只有 HTTPS 連線會送出 Cookie。預設 false。正式環境強烈建議啟用。

httponly（禁止 JS 存取）

設 true 可防 XSS 攻擊竊取 Cookie。現代框架預設開啟。

實用範例

設定 Cookie

$value = 'user_pref_data';
setcookie('TestCookie', $value);                              // Session Cookie
setcookie('TestCookie', $value, time() + 3600);               // 1小時
setcookie('TestCookie', $value, time() + 3600, '/', '.example.com', true, true); // 完整參數

讀取 Cookie

<?php
echo $_COOKIE['TestCookie'] ?? '未設定';
print_r($_COOKIE); // 除錯用：顯示所有 Cookie
?>

刪除 Cookie

將過期時間設為過去：

setcookie('TestCookie', '', time() - 3600);
setcookie('TestCookie', '', time() - 3600, '/', '.example.com', true, true);

陣列式 Cookie（多值單一名稱）

<?php
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>";
    }
}
/*
輸出：
three : cookiethree
two : cookietwo
one : cookieone
*/
?>

常見坑與注意事項

1. 輸出前呼叫：連空白行、BOM 都會導致失敗。習慣把 setcookie() 放在檔案最頂端。
2. 域名設定：跨子網域共用 Cookie 必須設 domain=.example.com。
3. 安全性：生產環境務必 secure=true, httponly=true；敏感資料改用 Session 或加密 Token。
4. 編碼：值含中文/特殊字元會自動編碼，讀取時自動解碼，通常無需手動處理。
5. 大小限制：單一 Cookie 約 4KB，總數每網域約 20-50 個，勿濫用。

總結

Cookie 基礎不難，關鍵在掌握 path、domain、secure、httponly 這四個安全與作用域參數。正確設定才能兼顧便利性與安全性。