README

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

安装

$> composer require dflydev/fig-cookies

概念

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

创建这些集合的方式如下

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

// Get a collection representing the cookies in the Set-Cookie headers
// of a PSR-7 Response
$setCookies = Dflydev\FigCookies\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都被表示为不可变值对象，所有修改器都将返回原始对象的新实例，带有所需的变化。

虽然这种设计风格有许多优点，但它可能会很快变得非常冗长。为了解决这个问题，FIG Cookies提供了两个外观，试图帮助简化事情，使整个过程更加简洁。

基本用法

开始使用FIG Cookies的最简单方法是使用FigRequestCookies和FigResponseCookies类。它们是原始FIG Cookies类的外观。它们的工作是将常见的cookie相关任务简化，使其比直接使用原始类更简洁。

创建Cookies和SetCookies以及重建请求和响应存在开销。每个FigCookies方法都会经历这个过程，所以请小心不要在相同的代码段中使用过多的这些调用。在某些情况下，直接使用原始FIG Cookies类可能比使用外观更好。

请求Cookies

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

use Dflydev\FigCookies\Cookie;

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

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

获取请求cookie

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

get的第三个可选参数设置了一个值，当cookie不存在时应使用此值。

use Dflydev\FigCookies\FigRequestCookies;

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

设置请求cookie

set方法将添加cookie或替换现有cookie。

Cookie原始对象用作第二个参数。

use Dflydev\FigCookies\FigRequestCookies;

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

修改请求cookie

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

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

use Dflydev\FigCookies\FigRequestCookies;

$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 = FigRequestCookies::modify($request, 'theme', $modify);

删除请求cookie

remove方法如果存在，则从请求头中删除cookie。

use Dflydev\FigCookies\FigRequestCookies;

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

请注意，这不会导致客户端删除cookie。请查看SetCookie类的expire()方法来完成此操作。

响应Cookies

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

use Dflydev\FigCookies\Modifier\SameSite;
use Dflydev\FigCookies\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，请使用FigResponseCookies门面。

获取响应Cookie

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

get的第三个可选参数设置了一个值，当cookie不存在时应使用此值。

use Dflydev\FigCookies\FigResponseCookies;

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

设置响应Cookie

set方法将添加cookie或替换现有cookie。

将SetCookie原始数据用作第二个参数。

use Dflydev\FigCookies\FigResponseCookies;

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

修改响应Cookie

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

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

use Dflydev\FigCookies\FigResponseCookies;

$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 = FigResponseCookies::modify($response, 'theme', $modify);

删除响应Cookie

remove方法将删除响应中存在的Cookie。

use Dflydev\FigCookies\FigResponseCookies;

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

使响应Cookie过期

expire方法设置一个具有远过期日期的Cookie。这会导致客户端删除该Cookie。

请注意，为了使Cookie过期，您需要配置其Set-Cookie头部，就像您最初写入Cookie时一样（即同一域名/路径）。最容易的方法是在设置和过期Cookie时重用配置头部的相同代码。

use Dflydev\FigCookies\FigResponseCookies;
use Dflydev\FigCookies\SetCookie;

$setCookie = SetCookie::create('ba')
    ->withValue('UQdfdafpJJ23k111m')
    ->withPath('/')
    ->withDomain('.example.com')
;

FigResponseCookies::set($response, $setCookie->expire());

常见问题解答

您调用setcookies吗？

不。

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

您处理会话吗？

不。

可以在FIG Cookies之上构建使用Cookie的会话处理，但这超出了此包的范围。

您从$_COOKIES中读取吗？

不。

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

许可证

MIT，请参阅LICENSE。

社区

想要参与其中？以下是一些方法

• 在irc.freenode.org上的#dflydev IRC频道中找到我们。
• 在Twitter上提及@dflydev。
•