README

PHP 的现代 cookie 管理

要求

PHP 8.1.0+

安装

通过 Composer 包含库 [?]
```
$ composer require pinga/cookie
```

包含 Composer 自动加载器

require __DIR__ . '/vendor/autoload.php';

升级

从此项目的早期版本迁移？请参阅我们的升级指南以获取帮助。

用法

静态方法

此库提供了一个与 PHP 内置的 setcookie(...) 函数兼容的静态方法，但包含对如 SameSite 属性等更新特性的支持。

\Delight\Cookie\Cookie::setcookie('SID', '31d4d96e407aad42');
// or
\Delight\Cookie\Cookie::setcookie('SID', '31d4d96e407aad42', time() + 3600, '/~rasmus/', 'example.com', true, true, 'Lax');

构建器模式

Cookie 类的实例允许您通过设置单个属性方便地构建 cookie。此类使用合理的默认值，可能与 setcookie 函数的默认值不同。

$cookie = new \Delight\Cookie\Cookie('SID');
$cookie->setValue('31d4d96e407aad42');
$cookie->setMaxAge(60 * 60 * 24);
// $cookie->setExpiryTime(time() + 60 * 60 * 24);
$cookie->setPath('/~rasmus/');
$cookie->setDomain('example.com');
$cookie->setHttpOnly(true);
$cookie->setSecureOnly(true);
$cookie->setSameSiteRestriction('Strict');

// echo $cookie;
// or
$cookie->save();
// or
// $cookie->saveAndSet();

方法调用也可以链式调用

(new \Delight\Cookie\Cookie('SID'))->setValue('31d4d96e407aad42')->setMaxAge(60 * 60 * 24)->setSameSiteRestriction('None')->save();

稍后可以像这样简单地删除 cookie

$cookie->delete();
// or
$cookie->deleteAndUnset();

注意：为了使删除生效，cookie 必须与最初保存的 cookie 具有相同的设置（除了其值，不需要设置）。因此，您应该记得再次传递适当的值给 setPath(...)、setDomain(...)、setHttpOnly(...) 和 setSecureOnly(...)。

读取 cookie

检查 cookie 是否存在

\Delight\Cookie\Cookie::exists('first_visit');

读取 cookie 的值（带可选默认值）

\Delight\Cookie\Cookie::get('first_visit');
// or
\Delight\Cookie\Cookie::get('first_visit', \time());

管理会话

使用 Session 类，您可以以与 PHP 内置的 session_start() 函数兼容的方式启动和恢复会话，同时还可以访问此库提供的改进的 cookie 处理功能。

// start session and have session cookie with 'lax' same-site restriction
\Delight\Cookie\Session::start();
// or
\Delight\Cookie\Session::start('Lax');

// start session and have session cookie with 'strict' same-site restriction
\Delight\Cookie\Session::start('Strict');

// start session and have session cookie without any same-site restriction
\Delight\Cookie\Session::start(null);
// or
\Delight\Cookie\Session::start('None'); // Chrome 80+

所有三个调用都尊重 PHP 的 session_set_cookie_params(...) 函数的设置以及配置选项 session.name、session.cookie_lifetime、session.cookie_path、session.cookie_domain、session.cookie_secure、session.cookie_httponly 和 session.use_cookies。

同样，通过

session_regenerate_id();
// and
session_regenerate_id(true);

提供

\Delight\Cookie\Session::regenerate();
// and
\Delight\Cookie\Session::regenerate(true);

如果您想利用改进的 cookie 处理功能来防止会话固定攻击。

此外，通过

\Delight\Cookie\Session::id();

提供对当前内部会话 ID 的访问，作为

session_id();

读取和写入会话数据

从会话中读取值（带可选默认值）

$value = \Delight\Cookie\Session::get($key);
// or
$value = \Delight\Cookie\Session::get($key, $defaultValue);

向会话写入值

\Delight\Cookie\Session::set($key, $value);

检查会话中是否存在值

if (\Delight\Cookie\Session::has($key)) {
    // ...
}

从会话中删除值
```
\Delight\Cookie\Session::delete($key);
```

读取 然后立即 从会话中删除值

$value = \Delight\Cookie\Session::take($key);
$value = \Delight\Cookie\Session::take($key, $defaultValue);

这对于闪存消息很有用，例如与 has(...) 方法结合使用。

解析 cookie

$cookieHeader = 'Set-Cookie: test=php.net; expires=Thu, 09-Jun-2016 16:30:32 GMT; Max-Age=3600; path=/~rasmus/; secure';
$cookieInstance = \Delight\Cookie\Cookie::parse($cookieHeader);

规范

RFC 2109
RFC 6265
Same-site Cookies（以前为 2016-06-20 和 2016-04-06）
- 修正案：默认为 Lax 并要求 None 的 secure 属性（注意：有不兼容的客户端）

贡献

欢迎所有贡献！如果您希望贡献，请先创建一个问题，以便讨论您的功能、问题或疑问。

许可协议

本项目遵循MIT 许可协议。

pinga / cookie

维护者

详细信息