包简介

Http cookie for PHP applications.

README 文档

README

The cookie service provides a way for managing cookies for PHP applications.

Getting started

Add the latest version of the cookie service project running this command.

composer require tobento/service-cookie

Requirements

PHP 8.4 or greater

Highlights

Framework-agnostic, will work with any project
Decoupled design

Documentation

Basic Usage

Simple example using the cookie service in your application:

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();
}

Using Middleware

You may prefer to use the Cookies middlware:

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)

Read and write cookies

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');
}

Read Cookie

Cookie Values Factory

You may use the CookieValuesFactory to create cookie values:

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)

You may check out the Cookie Values to learn more about it.

createCookieValuesFromCookies

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

$factory = new CookieValuesFactory();

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

You may check out the Cookie Values to learn more about it.

You may check out the Cookies to learn more about it.

Cookie Values

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

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

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

get

Get a cookie value by name.

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

Check if a cookie value by name exists.

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

Get a cookie values.

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

Map over each of the cookie values returning a new instance.

use Tobento\Service\Cookie\CookieValues;

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

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

withValues

Returns a new instance with the specified values.

use Tobento\Service\Cookie\CookieValues;

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

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

Write Cookie