README

管理 PSR-7 请求和响应的 Cookies。

这是从 dflydev/dflydev-fig-cookies 维护并工作的分支，因为该库似乎已被弃用。

安装

$> composer require anoixis/cookies

概念

tank Cookies 解决了两个问题，管理 Cookie 请求 标头和管理 Set-Cookie 响应 标头。它是通过引入一个 Cookies 类来管理 Cookie 实例的集合，以及一个 SetCookies 类来管理 SetCookie 实例的集合来实现的。

实例化这些集合看起来像这样

// Get a collection representing the cookies in the Cookie headers
// of a PSR-7 Request.
$cookies = Anoixis\Cookies\Cookies::fromRequest($request);

// Get a collection representing the cookies in the Set-Cookie headers
// of a PSR-7 Response
$setCookies = Anoixis\Cookies\SetCookies::fromResponse($response);

在以某种方式修改这些集合之后，它们将被渲染成 PSR-7 请求或 PSR-7 响应，如下所示

// Render the Cookie headers and add them to the headers of a
// PSR-7 Request.
$request = $cookies->renderIntoCookieHeader($request);

// Render the Set-Cookie headers and add them to the headers of a
// PSR-7 Response.
$response = $setCookies->renderIntoSetCookieHeader($response);

与 PSR-7 消息一样，Cookie、Cookies、SetCookie 和 SetCookies 都表示为不可变值对象，并且所有修改器都将返回原始对象的新实例，具有所请求的更改。

虽然这种设计风格有许多优点，但它可以非常快地变得相当冗长。为了解决这个问题，Tank Cookies 提供了两个外观，试图帮助简化问题，并使整个过程不那么冗长。

基本用法

开始使用 Tank Cookies 的最简单方法是使用 RequestCookies 和 ResponseCookies 类。它们是原始 Tank Cookies 类的外观。它们的任务是使常见的与 Cookie 相关的任务比直接使用原始类更容易和更简洁。

创建 Cookies 和 SetCookies 以及重建请求和响应会有开销。每个 Cookies 方法都会经历这个过程，因此在使用这些调用时请谨慎。在某些情况下，直接使用原始 Tank Cookies 类可能比使用外观更好。

请求 Cookies

请求在 Cookie 请求头中包含 cookie 信息。此头中的 cookie 由 Cookie 类表示。

use Anoixis\Cookies\Cookie;

$cookie = Cookie::create('theme', 'blue');

要轻松处理请求 cookie，请使用 RequestCookies 外观。

获取请求 Cookie

get 方法将返回一个 Cookie 实例。如果不存在指定名称的 cookie，则返回的 Cookie 实例将具有 null 值。

get 的可选第三个参数设置了一个值，如果 cookie 不存在，则使用此值。

use Anoixis\Cookies\RequestCookies;

$cookie = RequestCookies::get($request, 'theme');
$cookie = RequestCookies::get($request, 'theme', 'default-theme');

设置请求 Cookie

《set》方法将添加一个cookie或替换现有的cookie。

将《Cookie》原始数据类型用作第二个参数。

use Anoixis\Cookies\RequestCookies;

$request = RequestCookies::set($request, Cookie::create('theme', 'blue'));

修改请求cookie

《modify》方法允许基于具有指定名称的当前cookie替换cookie的内容。第三个参数是一个callable，它接受一个Cookie实例作为第一个参数，并期望返回一个Cookie实例。

如果不存在指定名称的cookie，将向callable传递一个具有null值的新的Cookie实例。

use Anoixis\Cookies\RequestCookies;

$modify = function (Cookie $cookie) {
    $value = $cookie->getValue();

    // ... inspect current $value and determine if $value should
    // change or if it can stay the same. in all cases, a cookie
    // should be returned from this callback...

    return $cookie->withValue($value);
}

$request = RequestCookies::modify($request, 'theme', $modify);

删除请求cookie

如果存在，则《remove》方法会删除cookie。

use Anoixis\Cookies\RequestCookies;

$request = RequestCookies::remove($request, 'theme');

请注意，这不会导致客户端删除cookie。请参阅《ResponseCookies::expire》来完成此操作。

响应cookie

响应在《Set-Cookie》响应头中包含cookie信息。这些头中的cookie由《SetCookie》类表示。

use Anoixis\Cookies\Modifier\SameSite;
use Anoixis\Cookies\SetCookie;

$setCookie = SetCookie::create('lu')
    ->withValue('Rg3vHJZnehYLjVg7qi3bZjzg')
    ->withExpires('Tue, 15-Jan-2013 21:47:38 GMT')
    ->withMaxAge(500)
    ->rememberForever()
    ->withPath('/')
    ->withDomain('.example.com')
    ->withSecure(true)
    ->withHttpOnly(true)
    ->withSameSite(SameSite::lax())
;

为了轻松处理响应cookie，请使用《ResponseCookies》外观。

获取响应cookie

《get》方法将返回一个《SetCookie》实例。如果不存在指定名称的cookie，则返回的《SetCookie》实例将具有null值。

get 的可选第三个参数设置了一个值，如果 cookie 不存在，则使用此值。

use Anoixis\Cookies\ResponseCookies;

$setCookie = ResponseCookies::get($response, 'theme');
$setCookie = ResponseCookies::get($response, 'theme', 'simple');

设置响应cookie

《set》方法将添加一个cookie或替换现有的cookie。

将《SetCookie》原始数据类型用作第二个参数。

use Anoixis\Cookies\ResponseCookies;

$response = ResponseCookies::set($response, SetCookie::create('token')
    ->withValue('a9s87dfz978a9')
    ->withDomain('example.com')
    ->withPath('/firewall')
);

修改响应cookie

《modify》方法允许基于具有指定名称的当前cookie替换cookie的内容。第三个参数是一个callable，它接受一个《SetCookie》实例作为第一个参数，并期望返回一个《SetCookie》实例。

如果不存在指定名称的cookie，则将具有null值的新的《SetCookie》实例传递给callable。

use Anoixis\Cookies\ResponseCookies;

$modify = function (SetCookie $setCookie) {
    $value = $setCookie->getValue();

    // ... inspect current $value and determine if $value should
    // change or if it can stay the same. in all cases, a cookie
    // should be returned from this callback...

    return $setCookie
        ->withValue($newValue)
        ->withExpires($newExpires)
    ;
}

$response = ResponseCookies::modify($response, 'theme', $modify);

删除响应cookie

如果存在，则《remove》方法将从响应中删除cookie。

use Anoixis\Cookies\ResponseCookies;

$response = ResponseCookies::remove($response, 'theme');

使响应cookie过期

《expire》方法将设置一个具有过去日期的cookie。这会导致客户端删除cookie。

use Anoixis\Cookies\ResponseCookies;

$response = ResponseCookies::expire($response, 'session_cookie');

常见问题解答（FAQ）

您是否调用了setcookies？

没有。

渲染的《SetCookie》实例的交付是PSR-7客户端实现的责任。

您对会话做了什么？

没有。

理论上可以在Tank Cookies的基础上构建会话处理，但这超出了本包的范围。

您是否从$_COOKIES中读取？

没有。

Tank Cookies 只关注 PSR-7 请求实例上的 Cookie 头部。在 ServerRequestInterface 实例的情况下，PSR-7 实现应该在头部包含 $_COOKIES 值，因此在这种情况下，Tank Cookies 可能会间接与 $_COOKIES 交互。

许可证

MIT 许可证，请参阅 LICENSE 文件。