README

安装

composer require bag2/cookie

动机

我们在 PHP 中 HTTP Set-Cookie 响应头方面遇到一些问题。

• 从 7.3.0 版本开始，PHP 的 setcookie() 函数开始支持 'SameSite' cookie 属性。
• 在 PHP 7.3.0 下发送 SameSite cookie 需要一个不寻常的技巧
• PSR-7 不提供针对 Cookies 的高级函数
• 在 PSR-7 时代，setcookie() 函数已无用处

此包提供了常见功能，无论您的项目是基于 PSR-7 还是 vanilla PHP（直接调用 setcookie() 函数）。

示例

创建 Cookie 烤箱

Oven 是一个可以存储多个 Set-Cookie 条目的对象。使用 CookieOvenBuilder 创建 Oven 对象。构造函数或 "with" 方法中指定的值构建了添加到 Set-Cookie 的选项的默认值。

<?php

use Bag2\Cookie\CookieOvenBuilder;

$now = \time();

// [Recomended] Create an Oven instance by CookieOvenBuilder
$cookie = (new CookieOvenBuilder)->withSameSite('Strict')->build();
$cookie->add('NameA', 'value 1', ['expires' => $now + 1200]);
$cookie->add('NameB', 'value 2', ['expires' => $now + 3600]);

// [Obsolete] Create an Oven instance by function
$cookie = Bag2\Cookie\oven(['secure' => true, 'httponly' => true, 'samesite' => 'Strict']);

Oven 通过键值对管理 cookies。请注意，CookieOven 只能有一个具有相同名称的 cookie。

传递给 Oven 构造函数的 $default_options 与传递给 CookieOven::add() 方法的 $option 结合。

接收到的 $options 与 PHP 7.3 中添加的 setcookie() 函数兼容。请参阅 PHP: setcookie - 手册。所有选项名称均为小写。

PSR-7

PSR-7 是由 PHP-FIG 定义的 HTTP 消息接口。

$response = $cookie->appendTo($response, $now);

// var_dump($response->getHeader('Set-Cookie'));
// => [
//   'Name1=value; expires=Sunday, 12-Jan-2020 08:25:56 UTC; Max-Age=3600',
//   'Name2=value; expires=Sunday, 12-Jan-2020 08:25:56 UTC; Max-Age=3600',
// ]

PSR-7 HTTP 消息对象是不可变的。如果您在 PSR-7 兼容的框架上编写代码，您可能只需 return 此值。

单元测试提示：Oven::appendTo() 和 Oven::setTo() 接收当前时间的 unixtime 以用于 SetCookie::compileHeaderLine()。原因是当前时间会影响 cookie 输出。该参数是可选的，但如果您想进行严格的输出值验证，则可从外部注入时间。

PHP setcookie() 包装器

如果您的项目允许您直接调用 setcookie()、header() 函数，则它是一种 vanilla PHP。

Bag2\Cookie\emit($cookie);

在此函数内部，选择与 PHP 版本匹配的 Emitter，并调用符合版本规范的 setcookie() 函数。

旧式 setcookie()

如果您不喜欢新的关联数组风格的 setcookie()，请使用 Bag2\Cookie\setcookie()。

Bag2\Cookie\setcookie('Cookie', 'value', \time() + 256, '/', '', true, true, 'Lax');

版权

此包根据 Apache License 2.0 许可。

版权 2020 Baguette HQ

根据 Apache License，版本 2.0（“许可证”）；除非遵守许可证，否则不得使用此文件。您可以在以下位置获得许可证副本：

https://apache.ac.cn/licenses/LICENSE-2.0

除非适用法律要求或书面同意，否则在许可证下分发的软件按照“现状”分发，不提供任何形式的明示或暗示担保或条件。请参阅许可证，了解具体的管理权限和限制的条款。