Final Class Yiisoft\User\Login\Cookie\CookieLogin
| Inheritance | Yiisoft\ |
|---|
The service is used to send or remove auto-login cookie.
The auto-login cookie value must be protected against tampering: either set a signature key here, or sign/encrypt
the cookie separately (for example with Yiisoft\). When a signature key is set, the
value is signed with HMAC-SHA256, so anyone able to edit the cookie can no longer change the identity or the
expiration timestamp without invalidating the signature.
See also:
Public Methods
| Method | Description | Defined By |
|---|---|---|
| __construct() | Yiisoft\ |
|
| addCookie() | Adds auto-login cookie to response so the user is logged in automatically based on cookie even if session is expired. | Yiisoft\ |
| expireCookie() | Expires auto-login cookie so user is not logged in automatically anymore. | Yiisoft\ |
| getCookieName() | Returns the auto-login cookie name. | Yiisoft\ |
| parseValue() | Parses the auto-login cookie value produced by {@see createValue()} back into the identity data. | Yiisoft\ |
| withCookieName() | Returns a new instance with the specified auto-login cookie name. | Yiisoft\ |
Constants
| Constant | Value | Description | Defined By |
|---|---|---|---|
| SIGNATURE_LENGTH | 64 | Length of a hexadecimal HMAC-SHA256 signature that prefixes a signed cookie value. | Yiisoft\ |
Method Details
| public mixed __construct ( DateInterval|null $duration = null, string|null $signatureKey = null, boolean $secureCookie = true ) | ||
| $duration | DateInterval|null |
Interval until the auto-login cookie expires. If it isn't set it means the auto-login cookie is session cookie that expires when browser is closed. |
| $signatureKey | string|null |
Secret key used to sign the auto-login cookie value with HMAC-SHA256. If it isn't set, the cookie value is stored without a signature and isn't protected against tampering. |
| $secureCookie | boolean |
Whether the client should send back the cookie only over HTTPS connection. |
public function __construct(
private readonly ?DateInterval $duration = null,
private readonly ?string $signatureKey = null,
private readonly bool $secureCookie = true,
) {}
Adds auto-login cookie to response so the user is logged in automatically based on cookie even if session is expired.
| public \ | ||
| $identity | Yiisoft\ |
The cookie login identity instance. |
| $response | \ |
Response for adding auto-login cookie. |
| $duration | DateInterval|false|null |
Interval until the auto-login cookie expires. If it is null it means the auto-login cookie is session cookie that expires when browser is closed. If it is false (by default) will be used default value of duration. |
| return | \ |
Response with added auto-login cookie. |
|---|---|---|
| throws | JsonException |
If an error occurs during JSON encoding of the cookie value. |
public function addCookie(
CookieLoginIdentityInterface $identity,
ResponseInterface $response,
DateInterval|false|null $duration = false,
): ResponseInterface {
$duration = $duration === false ? $this->duration : $duration;
$expires = $duration === null ? null : (new DateTimeImmutable())->add($duration);
$cookieValue = $this->createValue((string) $identity->getId(), $identity->getCookieLoginKey(), $expires);
return (new Cookie(name: $this->cookieName, value: $cookieValue, expires: $expires, secure: $this->secureCookie))
->addToResponse($response);
}
Expires auto-login cookie so user is not logged in automatically anymore.
| public \ | ||
| $response | \ |
Response for adding auto-login cookie. |
| return | \ |
Response with added auto-login cookie. |
|---|---|---|
public function expireCookie(ResponseInterface $response): ResponseInterface
{
return (new Cookie($this->cookieName, secure: $this->secureCookie))
->expire()
->addToResponse($response);
}
Returns the auto-login cookie name.
| public string getCookieName ( ) | ||
| return | string |
The auto-login cookie name. |
|---|---|---|
public function getCookieName(): string
{
return $this->cookieName;
}
Parses the auto-login cookie value produced by {@see createValue()} back into the identity data.
When a signature key is set, a value without a valid signature is rejected.
| public array|null parseValue ( string $value ) | ||
| $value | string |
The auto-login cookie value. |
| return | array|null |
The identity data, or |
|---|---|---|
public function parseValue(string $value): ?array
{
$payload = $this->signatureKey === null ? $value : $this->getVerifiedPayload($value, $this->signatureKey);
if ($payload === null) {
return null;
}
try {
$data = json_decode($payload, true, 512, JSON_THROW_ON_ERROR);
} catch (Throwable) {
return null;
}
if (!is_array($data) || !array_is_list($data) || count($data) !== 3) {
return null;
}
/** @psalm-var array{0: scalar, 1: scalar, 2: scalar} $data */
[$id, $key, $expires] = $data;
return [
'id' => (string) $id,
'key' => (string) $key,
'expires' => (int) $expires,
];
}
Returns a new instance with the specified auto-login cookie name.
| public self withCookieName ( string $name ) | ||
| $name | string |
The auto-login cookie name. |
public function withCookieName(string $name): self
{
$new = clone $this;
$new->cookieName = $name;
return $new;
}
User Contributed Notes
Leave a comment
Join the conversation to share a note.