Cookie

HTTP Cookie（网页 Cookie，浏览器 Cookie）是服务器发送给用户网页浏览器的少量数据。浏览器可以存储它并在以后向同一服务器发送请求时将其发送回去。通常，它用于判断两个请求是否来自同一个浏览器 - 例如，保持用户登录状态。它为无状态的 HTTP 协议记住有状态信息。

Cookie 主要用于三个目的

会话管理：登录、购物车、游戏得分或服务器应记住的任何其他内容
个性化：用户偏好、主题和其他设置
跟踪：记录和分析用户行为

为了帮助您有效地将 Cookie 发送到浏览器，CodeIgniter 提供了 CodeIgniter\Cookie\Cookie 类来抽象 Cookie 交互。

创建 Cookie 

目前有四 (4) 种方法可以创建一个新的 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 类中保存的默认值填充。

覆盖默认值 

要覆盖当前存储在类中的默认值，可以将 Config\Cookie 实例或默认值数组传递给静态 Cookie::setDefaults() 方法。

<?php

use CodeIgniter\Cookie\Cookie;
use Config\Cookie as CookieConfig;

// pass in a Config\Cookie instance before constructing a Cookie class
Cookie::setDefaults(new CookieConfig());
$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');

将 Config\Cookie 实例或数组传递给 Cookie::setDefaults() 将有效地覆盖您的默认值，并将持续存在，直到传递新的默认值。

更改默认值以限制时间

如果您不希望这种行为，而只想在有限的时间内更改默认值，则可以利用 Cookie::setDefaults() 返回值，该返回值返回旧的默认值数组。

<?php

use CodeIgniter\Cookie\Cookie;
use Config\Cookie as CookieConfig;

$oldDefaults = Cookie::setDefaults(new CookieConfig());
$cookie      = new Cookie('my_token', 'muffins');

// return the old defaults
Cookie::setDefaults($oldDefaults);

不可变 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 

在响应对象的 CookieStore 中设置 Cookie 对象，框架将自动发送 cookie。

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

<?php

use CodeIgniter\Cookie\Cookie;
use Config\Services;

$response = Services::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 个性化 

在 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\|none\|strict''`	`Lax`	SameSite 属性。
$raw	`true/false`	`false`	是否使用 `setrawcookie()` 发送。

在运行时，您可以使用 Cookie::setDefaults() 方法手动提供新的默认值。

类参考 

class CodeIgniter\Cookie\CookieStore

static fromCookieHeaders(array $headers[, bool $raw = false])

参数:

$header (array) – Set-Cookie 头部的数组
$raw (bool) – 是否不使用 URL 编码

返回类型:

CookieStore

返回值:

CookieStore 实例

抛出:

CookieException

从 Set-Cookie 头部的数组创建 CookieStore。

__construct(array $cookies)

参数:

$cookies (array) – Cookie 对象的数组

返回类型:

CookieStore

返回值:

CookieStore 实例

抛出:

CookieException

has(string $name[, string $prefix = ''[, ?string $value = null]]) → bool

参数:

$name (string) – Cookie 名称
$prefix (string) – Cookie 前缀
$value (string|null) – Cookie 值

返回类型:

bool

返回值:

检查集合中是否存在由名称和前缀标识的 Cookie 对象。

get(string $name[, string $prefix = '']) → Cookie

参数:

$name (string) – Cookie 名称
$prefix (string) – Cookie 前缀

返回类型:

Cookie

返回值:

检索由名称和前缀标识的 Cookie 实例。

抛出:

CookieException

put(Cookie $cookie) → CookieStore

参数:

$cookie (Cookie) – Cookie 对象

返回类型:

CookieStore

返回值:

新的 CookieStore 实例

存储新的 cookie 并返回新的集合。原始集合保持不变。

remove(string $name[, string $prefix = '']) → CookieStore

参数:

$name (string) – Cookie 名称
$prefix (string) – Cookie 前缀

返回类型:

CookieStore

返回值:

新的 CookieStore 实例

从集合中移除 cookie 并返回更新后的集合。原始集合保持不变。

dispatch() → void

返回类型:: void

分发存储中的所有 Cookie。

display() → array

返回类型:: array
返回值:: 返回存储中的所有 Cookie 实例。

clear() → void

返回类型:: void

清除 Cookie 集合。