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

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==')

Documentation

Internals

If you need help or have a question, the Yii Forum is a good place for that. You may also check out other Yii Community Resources.

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.

yiisoft / cookies

Maintainers

Details