Cookie

HTTP Cookie (网页 Cookie、浏览器 Cookie)是服务器发送到用户浏览器的一小段数据。浏览器会存储该数据并在后续向同一服务器发起请求时将其带回。通常用于判断两个请求是否来自同一浏览器——例如保持用户登录状态。它为无状态的 HTTP 协议提供了状态信息记忆能力。

Cookies 主要用于以下三个场景:

会话管理:登录状态、购物车、游戏分数等需要服务器记忆的信息
个性化设置:用户偏好、主题及其他配置
行为追踪:记录和分析用户行为

为帮助你高效地向浏览器发送 Cookies,CodeIgniter 提供了 CodeIgniter\Cookie\Cookie 类来抽象化 Cookie 交互。

创建 Cookie 

目前有四种方式创建新的 Cookie 值对象:

<?php
use CodeIgniter\Cookie\Cookie;
use DateTime;
// Using the constructor
$cookie = new Cookie(
 'remember_token',
 'f699c7fd18a8e082d0228932f3acd40e1ef5ef92efcedda32842a211d62f0aa6',
 [
 'expires' => new DateTime('+2 hours'),
 'prefix' => '__Secure-',
 'path' => '/',
 'domain' => '',
 'secure' => true,
 'httponly' => true,
 'raw' => false,
 'samesite' => Cookie::SAMESITE_LAX,
 ],
);
// Supplying a Set-Cookie header string
$cookie = Cookie::fromHeaderString(
 'remember_token=f699c7fd18a8e082d0228932f3acd40e1ef5ef92efcedda32842a211d62f0aa6; Path=/; Secure; HttpOnly; SameSite=Lax',
 false, // raw
);
// Using the fluent builder interface
$cookie = (new Cookie('remember_token'))
 ->withValue('f699c7fd18a8e082d0228932f3acd40e1ef5ef92efcedda32842a211d62f0aa6')
 ->withPrefix('__Secure-')
 ->withExpires(new DateTime('+2 hours'))
 ->withPath('/')
 ->withDomain('')
 ->withSecure(true)
 ->withHTTPOnly(true)
 ->withSameSite(Cookie::SAMESITE_LAX);
// Using the global function `cookie` which implicitly calls `new Cookie()`
$cookie = cookie('remember_token', 'f699c7fd18a8e082d0228932f3acd40e1ef5ef92efcedda32842a211d62f0aa6');

构建 Cookie 对象时,仅 name 属性为必填项,其他属性均为可选。若未修改可选属性,它们的值将由 Cookie 类中保存的默认值填充。

覆盖默认值 

要覆盖类中存储的默认值,可以通过静态方法 Cookie::setDefaults() 传入 Config\Cookie 实例或包含默认值的数组:

<?php
use CodeIgniter\Cookie\Cookie;
use Config\Cookie as CookieConfig;
// pass in a Config\Cookie instance before constructing a Cookie class
Cookie::setDefaults(config(CookieConfig::class));
$cookie = new Cookie('login_token');
// pass in an array of defaults
$myDefaults = [
 'expires' => 0,
 'samesite' => Cookie::SAMESITE_STRICT,
];
Cookie::setDefaults($myDefaults);
$cookie = new Cookie('login_token');

向 Cookie::setDefaults() 传递 Config\Cookie 实例或数组将永久覆盖默认值,直到传入新的默认值为止。

临时修改默认值

若希望临时修改默认值而非永久覆盖,可利用 Cookie::setDefaults() 返回旧默认值数组的特性:

<?php
use CodeIgniter\Cookie\Cookie;
use Config\Cookie as CookieConfig;
$oldDefaults = Cookie::setDefaults(config(CookieConfig::class));
$cookie = new Cookie('my_token', 'muffins');
// return the old defaults
Cookie::setDefaults($oldDefaults);

访问 Cookie 属性 

实例化后,可通过 getter 方法轻松访问 Cookie 属性:

<?php
use CodeIgniter\Cookie\Cookie;
use DateTime;
use DateTimeZone;
$cookie = new Cookie(
 'remember_token',
 'f699c7fd18a8e082d0228932f3acd40e1ef5ef92efcedda32842a211d62f0aa6',
 [
 'expires' => new DateTime('2025年02月14日 00:00:00', new DateTimeZone('UTC')),
 'prefix' => '__Secure-',
 'path' => '/',
 'domain' => '',
 'secure' => true,
 'httponly' => true,
 'raw' => false,
 'samesite' => Cookie::SAMESITE_LAX,
 ],
);
$cookie->getName(); // 'remember_token'
$cookie->getPrefix(); // '__Secure-'
$cookie->getPrefixedName(); // '__Secure-remember_token'
$cookie->getExpiresTimestamp(); // UNIX timestamp
$cookie->getExpiresString(); // 'Fri, 14-Feb-2025 00:00:00 GMT'
$cookie->isExpired(); // false
$cookie->getMaxAge(); // the difference from time() to expires
$cookie->isRaw(); // false
$cookie->isSecure(); // true
$cookie->getPath(); // '/'
$cookie->getDomain(); // ''
$cookie->isHTTPOnly(); // true
$cookie->getSameSite(); // 'Lax'
// additional getter
$cookie->getId(); // '__Secure-remember_token;;/'
// when using `setcookie()`'s alternative signature on PHP 7.3+
// you can easily use the `getOptions()` method to supply the
// $options parameter
$cookie->getOptions();

不可变 Cookie 

Cookie 实例是 HTTP Cookie 的不可变值对象。由于其不可变性,修改实例属性不会影响原实例,修改操作始终返回新实例。需保留新实例方可使用:

<?php
use CodeIgniter\Cookie\Cookie;
$cookie = new Cookie('login_token', 'admin');
$cookie->getName(); // 'login_token'
$cookie->withName('remember_token');
$cookie->getName(); // 'login_token'
$new = $cookie->withName('remember_token');
$new->getName(); // 'remember_token'

验证 Cookie 属性 

HTTP Cookie 受多个规范约束以确保浏览器接受。因此在创建或修改 Cookie 的某些属性时,会进行规范符合性验证。若验证失败将抛出 CookieException。

验证名称属性 

Cookie 名称可为任意 US-ASCII 字符,但以下字符除外:

控制字符
空格或制表符
分隔字符:( ) < > @ , ; : \ " / [ ] ? = { }

若设置 $raw 参数为 true 将执行严格验证,因为 PHP 的 setcookie() 和 setrawcookie() 会拒绝无效名称。此外,名称不能为空字符串。

验证前缀属性 

使用 __Secure- 前缀时,必须设置 $secure 标志为 true。使用 __Host- 前缀时需满足:

$secure 标志设为 true
$domain 为空
$path 必须为 /

验证 SameSite 属性 

SameSite 属性接受三个值:

Lax (宽松模式):跨站子请求(如图片加载)不发送 Cookie,但导航到源站时(如点击链接)会发送
Strict (严格模式):仅在第一方上下文中发送 Cookie
None (无限制):所有上下文中均发送 Cookie

CodeIgniter 允许将 SameSite 设为空字符串,此时使用 Cookie 类保存的默认值。可通过上文所述的 Cookie::setDefaults() 修改默认值。

现代浏览器规范要求未指定 SameSite 时默认使用 Lax。若 SameSite 设为空字符串且默认值也为空,则 Cookie 将被赋予 Lax 值。

当设置 SameSite 为 None 时,必须同时设置 Secure 为 true。

Cookie 类接受不区分大小写的 SameSite 值,也可使用类常量简化操作:

<?php
use CodeIgniter\Cookie\Cookie;
Cookie::SAMESITE_LAX; // 'lax'
Cookie::SAMESITE_STRICT; // 'strict'
Cookie::SAMESITE_NONE; // 'none'

发送 Cookie 

将 Cookie 对象存入 Response 对象的 CookieStore 中,框架会自动发送 Cookie。

使用 CodeIgniter\HTTP\Response::setCookie() 设置:

<?php
use CodeIgniter\Cookie\Cookie;
$response = service('response');
$cookie = new Cookie(
 'remember_token',
 'f699c7fd18a8e082d0228932f3acd40e1ef5ef92efcedda32842a211d62f0aa6',
 [
 'max-age' => 3600 * 2, // Expires in 2 hours
 ],
);
$response->setCookie($cookie);

也可使用 set_cookie() 辅助函数:

<?php
use CodeIgniter\Cookie\Cookie;
helper('cookie');
$cookie = new Cookie(
 'remember_token',
 'f699c7fd18a8e082d0228932f3acd40e1ef5ef92efcedda32842a211d62f0aa6',
 [
 'max-age' => 3600 * 2, // Expires in 2 hours
 ],
);
set_cookie($cookie);

使用 Cookie 存储库 

备注

通常无需直接操作 CookieStore。

CookieStore 类表示 Cookie 对象的不可变集合。

从 Response 获取存储库 

可通过当前 Response 对象访问 CookieStore 实例:

<?php
$cookieStore = service('response')->getCookieStore();

创建 CookieStore 

CodeIgniter 提供三种方式创建新 CookieStore 实例:

<?php
use CodeIgniter\Cookie\Cookie;
use CodeIgniter\Cookie\CookieStore;
// Passing an array of `Cookie` objects in the constructor
$store = new CookieStore([
 new Cookie('login_token'),
 new Cookie('remember_token'),
]);
// Passing an array of `Set-Cookie` header strings
$store = CookieStore::fromCookieHeaders([
 'remember_token=me; Path=/; SameSite=Lax',
 'login_token=admin; Path=/; SameSite=Lax',
]);
// using the global `cookies` function
$store = cookies([new Cookie('login_token')], false);
// retrieving the `CookieStore` instance saved in our current `Response` object
$store = cookies();

备注

使用全局函数 cookies() 时,仅当第二个参数 $getGlobal 设为 false 时才会考虑传入的 Cookie 数组。

检查存储库中的 Cookie 

可通过多种方式检查 CookieStore 实例中是否存在某 Cookie 对象:

<?php
use CodeIgniter\Cookie\Cookie;
use CodeIgniter\Cookie\CookieStore;
// check if cookie is in the current cookie collection
$store = new CookieStore([
 new Cookie('login_token'),
 new Cookie('remember_token'),
]);
$store->has('login_token');
// check if cookie is in the current Response's cookie collection
cookies()->has('login_token');
service('response')->hasCookie('remember_token');
// using the cookie helper to check the current Response
// not available to v4.1.1 and lower
helper('cookie');
has_cookie('login_token');

获取存储库中的 Cookie 

从 Cookie 集合中检索 Cookie 实例非常简单:

<?php
use CodeIgniter\Cookie\Cookie;
use CodeIgniter\Cookie\CookieStore;
use Config\Services;
// getting cookie in the current cookie collection
$store = new CookieStore([
 new Cookie('login_token'),
 new Cookie('remember_token'),
]);
$store->get('login_token');
// getting cookie in the current Response's cookie collection
cookies()->get('login_token');
service('response')->getCookie('remember_token');
// using the cookie helper to get cookie from the Response's cookie collection
helper('cookie');
get_cookie('remember_token');

直接从 CookieStore 获取实例时,无效名称会抛出 CookieException:

<?php
// throws CookieException
$store->get('unknown_cookie');

从当前 Response 的 Cookie 集合获取时,无效名称返回 null:

<?php
cookies()->get('unknown_cookie'); // null

若从 Response 获取时不带参数,将显示存储库中所有 Cookie 对象:

<?php
cookies()->display(); // array of Cookie objects
// or even from the Response
service('response')->getCookies();

备注

辅助函数 get_cookie() 从当前 Request 对象而非 Response 获取 Cookie。该函数检查 $_COOKIE 数组并直接获取。

添加/删除存储库中的 Cookie 

如前所述,CookieStore 对象不可变。需保存修改后的实例才能生效,原实例保持不变:

<?php
use CodeIgniter\Cookie\Cookie;
use CodeIgniter\Cookie\CookieStore;
$store = new CookieStore([
 new Cookie('login_token'),
 new Cookie('remember_token'),
]);
// adding a new Cookie instance
$new = $store->put(new Cookie('admin_token', 'yes'));
// removing a Cookie instance
$new = $store->remove('login_token');

备注

从存储库删除 Cookie 不会从浏览器删除。若要从浏览器删除 Cookie,必须向存储库添加同名空值 Cookie。

与当前 Response 对象中的 Cookies 交互时,可安全添加/删除 Cookies,无需担心集合的不可变性。Response 对象会自动替换为修改后的实例:

<?php
service('response')->setCookie('admin_token', 'yes');
service('response')->deleteCookie('login_token');
// using the cookie helper
helper('cookie');
set_cookie('admin_token', 'yes');
delete_cookie('login_token');

分发存储库中的 Cookie 

重要

该方法在 4.1.6 版本弃用,4.6.0 版本移除。

通常无需手动发送 Cookie,CodeIgniter 会自动处理。如需手动发送,可使用 dispatch 方法。需通过 headers_sent() 检查确保标头未发送:

<?php
use CodeIgniter\Cookie\Cookie;
use CodeIgniter\Cookie\CookieStore;
$store = new CookieStore([
 new Cookie('login_token'),
 new Cookie('remember_token'),
]);
$store->dispatch(); // After dispatch, the collection is now empty.

Cookie 个性化配置 

Cookie 类已预设合理默认值以确保正常创建。可通过修改 app/Config/Cookie.php 中的 Config\Cookie 类配置项来自定义:

设置项	选项/类型	默认值	描述
$prefix	`string`	`''`	Cookie 名前缀
$expires	`DateTimeInterface\|string\|int`	`0`	过期时间戳
$path	`string`	`/`	Cookie 路径属性
$domain	`string`	`''`	Cookie 域名属性(带尾部斜线)
$secure	`true`/`false`	`false`	是否仅通过 HTTPS 发送
$httponly	`true`/`false`	`true`	是否禁止 JavaScript 访问
$samesite	`Lax`/`None`/`Strict`	`Lax`	SameSite 属性
$raw	`true`/`false`	`false`	是否使用 `setrawcookie()` 发送

运行时可通过 Cookie::setDefaults() 方法手动设置新默认值。