yiisoft/cookies

Convenient way to use cookies with PSR-7

1.2.1 2022-06-15 08:37 UTC

Requires

• php: ^7.4|^8.0
• psr/http-message: ^1.0
• psr/http-message-implementation: 1.0
• psr/http-server-handler: ^1.0
• psr/http-server-middleware: ^1.0
• psr/log: ^1.1|^2.0|^3.0
• yiisoft/http: ^1.2
• yiisoft/security: ^1.0
• yiisoft/strings: ^2.0

Requires (Dev)

• httpsoft/http-message: ^1.0
• phpunit/phpunit: ^9.5
• roave/infection-static-analysis-plugin: ^1.16
• spatie/phpunit-watcher: ^1.23
• vimeo/psalm: ^4.18
• yiisoft/test-support: ^1.3

BSD-3-Clause

• cookies
• cookie
• psr-7

README

Yii Cookies

The package helps in working with HTTP cookies in a PSR-7 environment:

• provides a handy abstraction representing a cookie
• allows dealing with many cookies at once
• forms and adds Set-Cookie headers to response
• signs a cookie to prevent its value from being tampered with
• encrypts a cookie to prevent its value from being tampered with
• provides PSR-15 middleware for encrypting and signing cookie values

Requirements

• PHP 7.4 or higher.

Installation

The package could be installed with composer:

composer require yiisoft/cookies --prefer-dist

General usage

Adding a cookie to response:

$cookie = (new \Yiisoft\Cookies\Cookie('cookieName', 'value'))
    ->withPath('/')
    ->withDomain('yiiframework.com')
    ->withHttpOnly(true)
    ->withSecure(true)
    ->withSameSite(\Yiisoft\Cookies\Cookie::SAME_SITE_STRICT)
    ->withMaxAge(new \DateInterval('P7D'));

$response = $cookie->addToResponse($response);

Modifying response cookies to be sent:

$cookies = \Yiisoft\Cookies\CookieCollection::fromResponse($response);
$cookies->expire('login');
$response = $cookies->setToResponse($response);

Getting request cookies:

$cookies = \Yiisoft\Cookies\CookieCollection::fromArray($request->getCookieParams());

Signing a cookie to prevent its value from being tampered with:

$cookie = new \Yiisoft\Cookies\Cookie('identity', 'identityValue');

// The secret key used to sign and validate cookies.
$key = '0my1xVkjCJnD_q1yr6lUxcAdpDlTMwiU';
$signer = new \Yiisoft\Cookies\CookieSigner($key);

// Prefixes unique hash based on the value of the cookie and a secret key.
$signedCookie = $signer->sign($cookie);

// Validates and get backs the cookie with clean value.
$cookie = $signer->validate($signedCookie);

// Before validation, check if the cookie is signed.
if ($signer->isSigned($cookie)) {
    $cookie = $signer->validate($cookie);
}

Encrypting a cookie to prevent its value from being tampered with:

$cookie = new \Yiisoft\Cookies\Cookie('identity', 'identityValue');

// The secret key used to sign and validate cookies.
$key = '0my1xVkjCJnD_q1yr6lUxcAdpDlTMwiU';
$encryptor = new \Yiisoft\Cookies\CookieEncryptor($key);

// Encrypts cookie value based on the secret key.
$encryptedCookie = $encryptor->encrypt($cookie);

// Validates, decrypts and get backs the cookie with clean value.
$cookie = $encryptor->decrypt($encryptedCookie);

// Before decryption, check if the cookie is encrypted.
if ($encryptor->isEncrypted($cookie)) {
    $cookie = $encryptor->decrypt($cookie);
}

Using a PSR-15 middleware to encrypt and sign cookie values.

/**
 * @var \Psr\Http\Message\ServerRequestInterface $request
 * @var \Psr\Http\Server\RequestHandlerInterface $handler
 * @var \Psr\Log\LoggerInterface $logger
 */

// The secret key used to sign and validate cookies.
$key = '0my1xVkjCJnD_q1yr6lUxcAdpDlTMwiU';
$signer = new \Yiisoft\Cookies\CookieSigner($key);
$encryptor = new \Yiisoft\Cookies\CookieEncryptor($key);

$cookiesSettings = [
    'identity' => \Yiisoft\Cookies\CookieMiddleware::ENCRYPT,
    'name_[1-9]' => \Yiisoft\Cookies\CookieMiddleware::SIGN,
    'prefix*' => \Yiisoft\Cookies\CookieMiddleware::SIGN,
];

$middleware = new \Yiisoft\Cookies\CookieMiddleware(
    $logger
    $encryptor,
    $signer,
    $cookiesSettings,
);

// The cookie parameter values from the request are decrypted/validated.
// The cookie values are encrypted/signed, and appended to the response.
$response = $middleware->process($request, $handler);

Create cookie with raw value that will not be encoded:

$cookie = (new \Yiisoft\Cookies\Cookie('cookieName'))
    ->withRawValue('ebaKUq90PhiHck_MR7st-E1SxhbYWiTsLo82mCTbNuAh7rgflx5LVsYfJJseyQCrODuVcJkTSYhm1WKte-l5lQ==')

See Yii guide to cookies for more info.

Testing

Unit testing

The package is tested with PHPUnit. To run tests:

./vendor/bin/phpunit

Mutation testing

The package tests are checked with Infection mutation framework with Infection Static Analysis Plugin. To run it:

./vendor/bin/roave-infection-static-analysis-plugin

Static analysis

The code is statically analyzed with Psalm. To run static analysis:

./vendor/bin/psalm

License

The Yii Cookies is free software. It is released under the terms of the BSD License. Please see LICENSE for more information.

Maintained by Yii Software.

Support the project

Follow updates