yiisoft / cookies
Convenient way to use cookies with PSR-7
Fund package maintenance!
Open Collective
yiisoft
Installs: 169 341
Dependents: 9
Suggesters: 0
Security: 0
Stars: 18
Watchers: 14
Forks: 3
Open Issues: 1
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
This package is auto-updated.
Last update: 2023-11-12 12:13:04 UTC
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.