README

该Cookie服务为管理PHP应用程序的Cookie提供了一种方法。

入门

使用以下命令添加运行cookie服务项目的最新版本。

composer require tobento/service-cookie

要求

PHP 8.0或更高版本

亮点

框架无关，适用于任何项目
解耦设计

文档

基本用法

使用cookie服务在您的应用程序中的简单示例

use Tobento\Service\Cookie;
use Tobento\Service\Encryption\EncrypterInterface;

// Set up cookie values for reading cookies:
$cookieValues = new Cookie\CookieValues($_COOKIE);

// You may use the default processor for decryption:
$processor = new Cookie\CookiesProcessor(
    encrypter: null, // null|EncrypterInterface
    whitelistedCookies: ['PHPSESSID'],
);

$cookieValues = $processor->processCookieValues($cookieValues);

// Start reading values:
$value = $cookieValues->get('foo');

// Set up Cookies for writing:
$cookies = new Cookie\Cookies(
    cookieFactory: new Cookie\CookieFactory(),
);

// Adding cookies:
$cookies->add('name', 'value');

// You may use the default processor for encryption:
$cookies = $processor->processCookies($cookies);

// Send cookies before any header is sent:
foreach($cookies as $cookie) {
    $cookie->send();
}

使用中间件

您可能更喜欢使用Cookies中间件

use Psr\Http\Server\MiddlewareInterface;
use Tobento\Service\Cookie\Middleware;
use Tobento\Service\Cookie\CookieValuesFactory;
use Tobento\Service\Cookie\CookiesFactory;
use Tobento\Service\Cookie\CookieFactory;
use Tobento\Service\Cookie\CookiesProcessor;
use Tobento\Service\Cookie\CookieValuesFactoryInterface;
use Tobento\Service\Cookie\CookiesFactoryInterface;
use Tobento\Service\Cookie\CookiesProcessorInterface;

$middleware = new Middleware\Cookies(
    // CookieValuesFactoryInterface
    cookieValuesFactory: new CookieValuesFactory(),
    
    // CookiesFactoryInterface
    cookiesFactory: new CookiesFactory(new CookieFactory()),
    
    // CookiesProcessorInterface
    cookiesProcessor: new CookiesProcessor(),
);

var_dump($middleware instanceof MiddlewareInterface);
// bool(true)

读取和写入Cookie

use Psr\Http\Message\ServerRequestInterface;
use Tobento\Service\Cookie\CookieValuesInterface;
use Tobento\Service\Cookie\CookiesInterface;

// ...

public function index(ServerRequestInterface $request): void
{
    // read cookies:
    $cookieValues = $request->getAttribute(CookieValuesInterface::class);
    
    $value = $cookieValues->get('foo');
    
    // or
    var_dump($request->getCookieParams());
    
    // write cookies:
    $cookies = $request->getAttribute(CookiesInterface::class);
    
    $cookies->add('name', 'value');
}

读取Cookie

Cookie值工厂

您可以使用CookieValuesFactory来创建Cookie值

createCookieValuesFromArray

use Tobento\Service\Cookie\CookieValuesFactory;
use Tobento\Service\Cookie\CookieValuesFactoryInterface;
use Tobento\Service\Cookie\CookieValuesInterface;

$factory = new CookieValuesFactory();

var_dump($factory instanceof CookieValuesFactoryInterface);
// bool(true)

$cookieValues = $factory->createCookieValuesFromArray($_COOKIE);

var_dump($cookieValues instanceof CookieValuesInterface);
// bool(true)

您可以查看Cookie值以了解更多信息。

createCookieValuesFromCookies

use Tobento\Service\Cookie\CookieValuesFactory;
use Tobento\Service\Cookie\CookiesInterface;

$factory = new CookieValuesFactory();

$cookieValues = $factory->createCookieValuesFromCookies(
    $cookies // CookiesInterface
);

您可以查看Cookie值以了解更多信息。

您可以查看Cookies以了解更多信息。

Cookie值

use Tobento\Service\Cookie\CookieValues;
use Tobento\Service\Cookie\CookieValuesInterface;

$cookieValues = new CookieValues(['name' => 'value']);

var_dump($cookieValues instanceof CookieValuesInterface);
// bool(true)

get

通过名称获取Cookie值。

use Tobento\Service\Cookie\CookieValues;

$values = new CookieValues([
    'name' => 'value',
    'meta' => [
        'color' => 'red',
    ],
]);

var_dump($values->get(name: 'name'));
// string(5) "value"

// supports array access:
var_dump($values['name']);

// supports dot notation:
var_dump($values->get(name: 'meta.color'));
// string(3) "red"

// with a default if not exists:
var_dump($values->get(name: 'foo', default: 'value'));
// string(5) "value"

var_dump($values->get(name: 'foo'));
// NULL

has

检查是否存在名为的Cookie值。

use Tobento\Service\Cookie\CookieValues;

$values = new CookieValues([
    'name' => 'value',
    'meta' => [
        'color' => 'red',
    ],
]);

var_dump($values->has(name: 'name'));
// bool(true)

// supports dot notation:
var_dump($values->has(name: 'meta.color'));
// bool(true)

var_dump($values->has(name: 'foo'));
// bool(false)

all

获取Cookie值。

use Tobento\Service\Cookie\CookieValues;

$values = new CookieValues([
    'name' => 'value',
    'meta' => [
        'color' => 'red',
    ],
]);

var_dump($values->all());
// array(2) {["name"]=> string(5) ... }

// or just
foreach($values as $value) {}

map

遍历每个Cookie值，返回一个新实例。

use Tobento\Service\Cookie\CookieValues;

$values = new CookieValues([
    'name' => 'value',
]);

$valuesNew = $values->map(function(mixed $value, string|int $name): mixed {
    return $value;
});

withValues

返回具有指定值的新实例。

use Tobento\Service\Cookie\CookieValues;

$values = new CookieValues([
    'name' => 'value',
]);

$valuesNew = $values->withValues(['name' => 'value']);

写入Cookie

Cookies工厂

您可以使用CookiesFactory来创建Cookie

createCookies

use Tobento\Service\Cookie\CookiesFactory;
use Tobento\Service\Cookie\CookiesFactoryInterface;
use Tobento\Service\Cookie\CookieFactory;
use Tobento\Service\Cookie\CookiesInterface;
use Tobento\Service\Cookie\CookieInterface;
use Tobento\Service\Cookie\Cookie;

$cookiesFactory = new CookiesFactory(
    cookieFactory: new CookieFactory(),
);

var_dump($cookiesFactory instanceof CookiesFactoryInterface);
// bool(true)

$cookies = $cookiesFactory->createCookies();

var_dump($cookies instanceof CookiesInterface);
// bool(true)

$cookies = $cookiesFactory->createCookies(
    new Cookie(name: 'name', value: 'value'),
);

您可以查看Cookie工厂以了解更多信息。

您可以查看Cookies以了解更多信息。

createCookiesFromKeyValuePairs

从键/值对创建新的Cookie。可用于从$_COOKIE超全局创建Cookie。

use Tobento\Service\Cookie\CookiesFactory;
use Tobento\Service\Cookie\CookieFactory;
use Tobento\Service\Cookie\CookiesInterface;

$cookiesFactory = new CookiesFactory(
    cookieFactory: new CookieFactory(),
);

$cookies = $cookiesFactory->createCookiesFromKeyValuePairs([
    'name' => 'value',
]);

var_dump($cookies instanceof CookiesInterface);
// bool(true)

您可以查看Cookie工厂以了解更多信息。

您可以查看Cookies以了解更多信息。

createCookiesFromArray

use Tobento\Service\Cookie\CookiesFactory;
use Tobento\Service\Cookie\CookieFactory;
use Tobento\Service\Cookie\CookiesInterface;

$cookiesFactory = new CookiesFactory(
    cookieFactory: new CookieFactory(),
);

$cookies = $cookiesFactory->createCookiesFromArray([
    [
        'name' => 'name',
        'value' => 'value',

        // The duration in seconds until the cookie will expire.
        'lifetime' => 3600,

        'path' => '/',
        'domain' => '.example.com',
        'secure' => true,
        'httpOnly' => true,
        'sameSite' => 'Lax',
    ],
]);

var_dump($cookies instanceof CookiesInterface);
// bool(true)

您可以查看Cookie工厂以了解更多信息。

您可以查看Cookies以了解更多信息。

Cookies

use Tobento\Service\Cookie\Cookies;
use Tobento\Service\Cookie\CookiesInterface;
use Tobento\Service\Cookie\CookieFactory;

$cookies = new Cookies(
    cookieFactory: new CookieFactory(),
);

var_dump($cookies instanceof CookiesInterface);
// bool(true)

您可以查看Cookie工厂以了解更多信息。

addCookie

添加一个Cookie对象。

use Tobento\Service\Cookie\Cookies;
use Tobento\Service\Cookie\CookieFactory;
use Tobento\Service\Cookie\Cookie;

$cookies = new Cookies(
    cookieFactory: new CookieFactory(),
);

$cookies->addCookie(
    new Cookie(name: 'name', value: 'value')
);

您可以查看Cookie工厂以了解更多信息。

add

添加一个Cookie。

use Tobento\Service\Cookie\Cookies;
use Tobento\Service\Cookie\CookieFactory;

$cookies = new Cookies(
    cookieFactory: new CookieFactory(),
);

$cookies->add(
    name: 'name', // string
    value: 'value', // string
    
    // The duration in seconds until the cookie will expire.
    lifetime: 3600, // null|int
    
    // if null (default) it uses default value from factory.
    path: '/', // null|string
    
    // if null (default) it uses default value from factory.
    domain: 'example.com', // null|string
    
    // if null (default) it uses default value from factory.
    secure: true, // null|bool
    
    httpOnly: true, // default true if not set
    
    // if null (default) it uses default value from factory.
    sameSite: 'Lax', // string
);

您可以通过自定义CookieFactory::class更改默认值。

您可以查看Cookie工厂以了解更多信息。

get

根据指定参数返回一个Cookie，如果未找到则返回null。

$cookie = $cookies->get(name: 'name');

// by name and path:
$cookie = $cookies->get(name: 'name', path: 'path');

// by name and domain:
$cookie = $cookies->get(name: 'name', domain: 'example.com');

// by name, path and domain:
$cookie = $cookies->get(name: 'name', path: 'path', domain: 'example.com');

clear

根据指定参数清除Cookie。

// clears all with the same name:
$cookies->clear(name: 'name');

// clears only with same name and path:
$cookies->clear(name: 'name', path: 'path');

// clears only with same name and domain:
$cookies->clear(name: 'name', domain: 'example.com');

// clears only with same name, path and domain:
$cookies->clear(name: 'name', path: 'path', domain: 'example.com');

column

有时您可能只需要从Cookie返回特定列的array。

$names = $cookies->column('name');

$values = $cookies->column('value');

// values keyed by name:
$values = $cookies->column('value', 'name');

first

返回第一个Cookie，否则返回null。

use Tobento\Service\Cookie\CookieInterface;

$cookie = $cookies->first();

var_dump($cookie instanceof CookieInterface);
// bool(true) or NULL

all

返回所有Cookie。

use Tobento\Service\Cookie\CookieInterface;

$cookies = $cookies->all();
// array<int, CookieInterface>

// or just
foreach($cookies as $cookie) {}

filter

返回具有过滤Cookie的新实例。

use Tobento\Service\Cookie\CookieInterface;

$cookiesNew = $cookies->filter(
    fn(CookieInterface $c): bool => $c->name() === 'foo'
);

name

返回具有名称过滤的新实例。

$cookiesNew = $cookies->name('foo');

path

返回具有路径过滤的新实例。

$cookiesNew = $cookies->path('/');

domain

返回具有域名过滤的新实例。

$cookiesNew = $cookies->domain('example.com');

map

遍历每个Cookie，返回一个新实例。

use Tobento\Service\Cookie\CookieInterface;

$cookiesNew = $cookies->map(function(CookieInterface $c): CookieInterface {
    return $c;
});

toHeader

返回Cookie头。

var_dump($cookies->toHeader());
// array(1) { [0]=> string(127) "name=value; Expires=Tuesday, 06-Jun-2023 18:34:46 GMT; Max-Age=3600; Path=/; Domain=example.com; Secure; HttpOnly; SameSite=Lax" }

Cookie工厂

您可以使用CookieFactory创建一个Cookie

createCookie

use Tobento\Service\Cookie\CookieFactory;
use Tobento\Service\Cookie\CookieFactoryInterface;
use Tobento\Service\Cookie\CookieInterface;

$cookieFactory = new CookieFactory(
    // default values:
    path: '/',
    domain: '',
    secure: true,
    sameSite: 'Lax',
);

var_dump($cookieFactory instanceof CookieFactoryInterface);
// bool(true)

$cookie = $cookieFactory->createCookie(
    name: 'name', // string
    value: 'value', // string
    
    // The duration in seconds until the cookie will expire.
    lifetime: 3600, // null|int
    
    // if null (default) it uses default value.
    path: '/', // null|string
    
    // if null (default) it uses default value.
    domain: 'example.com', // null|string
    
    // if null (default) it uses default value.
    secure: true, // null|bool
    
    httpOnly: true, // default true if not set
    
    // if null (default) it uses default value.
    sameSite: 'Lax', // string
);

var_dump($cookie instanceof CookieInterface);
// bool(true)

您可以查看Cookie以了解更多信息。

createCookieFromArray

use Tobento\Service\Cookie\CookieFactory;
use Tobento\Service\Cookie\CookieInterface;

$cookieFactory = new CookieFactory(
    // default values:
    path: '/',
    domain: '',
    secure: true,
    sameSite: 'Lax',
);

$cookie = $cookieFactory->createCookieFromArray([
    'name' => 'name',
    'value' => 'value',

    // The duration in seconds until the cookie will expire.
    'lifetime' => 3600,

    'path' => '/',
    'domain' => '.example.com',
    'secure' => true,
    'httpOnly' => true,
    'sameSite' => 'Lax',
]);

var_dump($cookie instanceof CookieInterface);
// bool(true)

您可以查看Cookie以了解更多信息。

Cookie

use Tobento\Service\Cookie\Cookie;
use Tobento\Service\Cookie\CookieInterface;
use Tobento\Service\Cookie\SameSite;
use Tobento\Service\Cookie\SameSiteInterface;

$cookie = new Cookie(
    name: 'name', // string
    value: 'value', // string
    
    // The duration in seconds until the cookie will expire.
    lifetime: 3600, // null|int
    
    path: '/', // string
    
    domain: '', // string
    
    secure: true, // bool
    
    httpOnly: true, // bool
    
    sameSite: new SameSite(value: 'Lax'), // null|SameSiteInterface
);

var_dump($cookie instanceof CookieInterface);
// bool(true)

var_dump($cookie->name());
// string(4) "name"

var_dump($cookie->value());
// string(5) "value"

var_dump($cookie->lifetime());
// int(3600) or NULL

var_dump($cookie->path());
// string(1) "/"

var_dump($cookie->domain());
// string(0) ""

var_dump($cookie->secure());
// bool(true)

var_dump($cookie->httpOnly());
// bool(true)

var_dump($cookie->sameSite());
// null|SameSiteInterface

var_dump($cookie->sameSite()?->value());
// string(3) "Lax"

var_dump($cookie->expires());
// int(1686155135) or NULL

var_dump($cookie->toHeader());
// string(109) "name=value; Expires=Wednesday, 07-Jun-2023 16:27:47 GMT; Max-Age=3600; Path=/; Secure; HttpOnly; SameSite=Lax"

// send the cookie uses setcookie() method:
var_dump($cookie->send());
// bool(true) on success, otherwise false

Cookies处理器

您可以使用默认的Cookie处理器来加密和解密Cookie值，或者您可以根据需要创建一个自定义处理器。

use Tobento\Service\Cookie\CookiesProcessor;
use Tobento\Service\Cookie\CookiesProcessorInterface;
use Tobento\Service\Encryption\EncrypterInterface;

$processor = new CookiesProcessor(
    encrypter: null, // null|EncrypterInterface
    whitelistedCookies: ['PHPSESSID'],
);

var_dump($processor instanceof CookiesProcessorInterface);
// bool(true)

查看加密服务以了解更多信息。

processCookieValues

解密Cookie值。

use Tobento\Service\Cookie\CookieValuesInterface;

$cookieValues = $processor->processCookieValues(
    cookieValues: $cookieValues // CookieValuesInterface
);

您可以查看Cookie值以了解更多信息。

processCookies

加密Cookie值。

use Tobento\Service\Cookie\CookiesInterface;

$cookieValues = $processor->processCookies(
    cookies: $cookies // CookiesInterface
);

您可以查看Cookies以了解更多信息。

whitelistCookie

您可以使用whitelistCookie来添加白名单中的cookie，这意味着不需要进行加密/解密操作。

$processor->whitelistCookie(name: 'foo');

whitelistedCookies

返回白名单中的cookie。

$whitelistedCookies = $processor->whitelistedCookies();
// array<int, string>

tobento / service-cookie

维护者

详细信息

README

目录

入门

要求

亮点

文档

基本用法

使用中间件

读取Cookie

Cookie值工厂

Cookie值

写入Cookie

Cookies工厂

Cookies

Cookie工厂

Cookie

Cookies处理器

致谢