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
- PHP 7.4 or higher.
The package could be installed with composer:
composer require yiisoft/cookies --prefer-dist
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.
The package is tested with PHPUnit. To run tests:
./vendor/bin/phpunit
The package tests are checked with Infection mutation framework with Infection Static Analysis Plugin. To run it:
./vendor/bin/roave-infection-static-analysis-plugin
The code is statically analyzed with Psalm. To run static analysis:
./vendor/bin/psalm
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.