0

Final Class Yiisoft\User\Login\Cookie\CookieLogin

InheritanceYiisoft\User\Login\Cookie\CookieLogin

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\Cookies\CookieMiddleware). 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

Hide inherited methods

Method Description Defined By
__construct() Yiisoft\User\Login\Cookie\CookieLogin
addCookie() Adds auto-login cookie to response so the user is logged in automatically based on cookie even if session is expired. Yiisoft\User\Login\Cookie\CookieLogin
expireCookie() Expires auto-login cookie so user is not logged in automatically anymore. Yiisoft\User\Login\Cookie\CookieLogin
getCookieName() Returns the auto-login cookie name. Yiisoft\User\Login\Cookie\CookieLogin
parseValue() Parses the auto-login cookie value produced by {@see createValue()} back into the identity data. Yiisoft\User\Login\Cookie\CookieLogin
withCookieName() Returns a new instance with the specified auto-login cookie name. Yiisoft\User\Login\Cookie\CookieLogin

Constants

Hide inherited constants

Constant Value Description Defined By
SIGNATURE_LENGTH 64 Length of a hexadecimal HMAC-SHA256 signature that prefixes a signed cookie value. Yiisoft\User\Login\Cookie\CookieLogin

Method Details

Hide inherited methods

__construct() public method

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,
) {}

            
addCookie() public method

Adds auto-login cookie to response so the user is logged in automatically based on cookie even if session is expired.

public \Psr\Http\Message\ResponseInterface addCookie ( Yiisoft\User\Login\Cookie\CookieLoginIdentityInterface $identity, \Psr\Http\Message\ResponseInterface $response, DateInterval|false|null $duration false )
$identity Yiisoft\User\Login\Cookie\CookieLoginIdentityInterface

The cookie login identity instance.

$response \Psr\Http\Message\ResponseInterface

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 \Psr\Http\Message\ResponseInterface

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);
}

            
expireCookie() public method

Expires auto-login cookie so user is not logged in automatically anymore.

public \Psr\Http\Message\ResponseInterface expireCookie ( \Psr\Http\Message\ResponseInterface $response )
$response \Psr\Http\Message\ResponseInterface

Response for adding auto-login cookie.

return \Psr\Http\Message\ResponseInterface

Response with added auto-login cookie.

                public function expireCookie(ResponseInterface $response): ResponseInterface
{
    return (new Cookie($this->cookieName, secure: $this->secureCookie))
        ->expire()
        ->addToResponse($response);
}

            
getCookieName() public method

Returns the auto-login cookie name.

public string getCookieName ( )
return string

The auto-login cookie name.

                public function getCookieName(): string
{
    return $this->cookieName;
}

            
parseValue() public method

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 null if the value is malformed or has an invalid signature.

                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,
    ];
}

            
withCookieName() public method

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;
}