Class Cookie

Cookie object to build a cookie and turn it into a header value

An HTTP cookie (also called web cookie, Internet cookie, browser cookie or simply cookie) is a small piece of data sent from a website and stored on the user's computer by the user's web browser while the user is browsing.

Cookies were designed to be a reliable mechanism for websites to remember stateful information (such as items added in the shopping cart in an online store) or to record the user's browsing activity (including clicking particular buttons, logging in, or recording which pages were visited in the past). They can also be used to remember arbitrary pieces of information that the user previously entered into form fields such as names, and preferences.

Cookie objects are immutable, and you must re-assign variables when modifying cookie objects:

$cookie = $cookie->withValue('0');

Namespace: Cake\Http\Cookie
See: \Cake\Http\Cookie\CookieCollection for working with collections of cookies.
See: \Cake\Http\Response::getCookieCollection() for working with response cookies.
Link: https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-03
Link: https://en.wikipedia.org/wiki/HTTP_cookie

Constants

string

EXPIRES_FORMAT ¶
```
'D, d-M-Y H:i:s T'
```
Expires attribute format.
string

SAMESITE_LAX ¶
```
'Lax'
```
SameSite attribute value: Lax
string

SAMESITE_NONE ¶
```
'None'
```
SameSite attribute value: None
string

SAMESITE_STRICT ¶
```
'Strict'
```
SameSite attribute value: Strict
array<string>

SAMESITE_VALUES ¶
```
[self::SAMESITE_LAX, self::SAMESITE_STRICT, self::SAMESITE_NONE]
```
Valid values for "SameSite" attribute.

Property Summary

$defaults protected static

array<string, mixed>

Default attributes for a cookie.
$domain protected

string

Domain
$expiresAt protected

DateTime|DateTimeImmutable|null

Expiration time
$httpOnly protected

bool

HTTP only
$isExpanded protected

bool

Whether a JSON value has been expanded into an array.
$name protected

string

Cookie name
$path protected

string

Path
$sameSite protected

string|null

Samesite
$secure protected

bool

Secure
$value protected

array|string

Raw Cookie value.

Method Summary

__construct() public

Constructor
_expand() protected

Explode method to return array from string set in CookieComponent::_flatten() Maintains reading backwards compatibility with 1.x CookieComponent::_flatten().
_flatten() protected

Implode method to keep keys are multidimensional arrays
_setValue() protected

Setter for the value attribute.
check() public

Checks if a value exists in the cookie data.
create() public static

Factory method to create Cookie instances.
createFromHeaderString() public static

Create Cookie instance from "set-cookie" header string.
dateTimeInstance() protected static

Converts non null expiry value into DateTimeInterface instance.
getDomain() public

Get the domain attribute.
getExpiresTimestamp() public

Get the timestamp from the expiration time
getExpiry() public

Get the current expiry time
getFormattedExpires() public

Builds the expiration value part of the header string
getId() public

Get the id for a cookie
getName() public

Gets the cookie name
getOptions() public

Get cookie options
getPath() public

Get the path attribute.
getSameSite() public

Get the SameSite attribute.
getScalarValue() public

Gets the cookie value as scalar.
getStringValue() public deprecated

Gets the cookie value as a string.
getValue() public

Gets the cookie value
isExpanded() public

Checks if the cookie value was expanded
isExpired() public

Check if a cookie is expired when compared to $time
isHttpOnly() public

Check if the cookie is HTTP only
isSecure() public

Check if the cookie is secure
read() public

Read data from the cookie
setDefaults() public static

Set default options for the cookies.
toArray() public

Get cookie data as array.
toHeaderValue() public

Returns a header value as string
validateName() protected

Validates the cookie name
validateSameSiteValue() protected static

Check that value passed for SameSite is valid.
withAddedValue() public

Create a new cookie with updated data.
withDomain() public

Create a cookie with an updated domain
withExpired() public

Create a new cookie that will expire/delete the cookie from the browser.
withExpiry() public

Create a cookie with an updated expiration date
withHttpOnly() public

Create a cookie with HTTP Only updated
withName() public

Sets the cookie name
withNeverExpire() public

Create a new cookie that will virtually never expire.
withPath() public

Create a new cookie with an updated path
withSameSite() public

Create a cookie with an updated SameSite option.
withSecure() public

Create a cookie with Secure updated
withValue() public

Create a cookie with an updated value.
withoutAddedValue() public

Create a new cookie without a specific path

Method Detail

__construct() ¶ public

__construct(string $name, array|string $value = '', DateTime|DateTimeImmutable|null $expiresAt = null, string|null $path = null, string|null $domain = null, bool|null $secure = null, bool|null $httpOnly = null, string|null $sameSite = null)

Constructor

The constructors args are similar to the native PHP setcookie() method. The only difference is the 3rd argument which excepts null or an DateTime or DateTimeImmutable object instead an integer.

Parameters

string $name: Cookie name
array|string $value optional: Value of the cookie
DateTime|DateTimeImmutable|null $expiresAt optional: Expiration time and date
string|null $path optional: Path
string|null $domain optional: Domain
bool|null $secure optional: Is secure
bool|null $httpOnly optional: HTTP Only
string|null $sameSite optional: Samesite

Links

https://php.net/manual/en/function.setcookie.php

_expand() ¶ protected

_expand(string $string): array|string

Explode method to return array from string set in CookieComponent::_flatten() Maintains reading backwards compatibility with 1.x CookieComponent::_flatten().

Parameters

string $string: A string containing JSON encoded data, or a bare string.

Returns

array|string

Map of key and values

_flatten() ¶ protected

_flatten(array $array): string

Implode method to keep keys are multidimensional arrays

Parameters

array $array: Map of key and values

Returns

string

A JSON encoded string.

_setValue() ¶ protected

_setValue(array|string $value): void

Setter for the value attribute.

Parameters

array|string $value: The value to store.

Returns

void

check() ¶ public

check(string $path): bool

Checks if a value exists in the cookie data.

This method will expand serialized complex data, on first use.

Parameters

string $path: Path to check

Returns

bool

create() ¶ public static

create(string $name, array|string $value, array<string, mixed> $options = []): static

Factory method to create Cookie instances.

Parameters

string $name: Cookie name
array|string $value: Value of the cookie
array<string, mixed> $options optional: Cookies options.

Returns

static

createFromHeaderString() ¶ public static

createFromHeaderString(string $cookie, array<string, mixed> $defaults = []): static

Create Cookie instance from "set-cookie" header string.

Parameters

string $cookie: Cookie header string.
array<string, mixed> $defaults optional: Default attributes.

Returns

static

dateTimeInstance() ¶ protected static

dateTimeInstance(mixed $expires): DateTime|DateTimeImmutable|null

Converts non null expiry value into DateTimeInterface instance.

Parameters

mixed $expires: Expiry value.

Returns

DateTime|DateTimeImmutable|null

getDomain() ¶ public

getDomain(): string

Get the domain attribute.

Returns

string

getExpiresTimestamp() ¶ public

getExpiresTimestamp(): int|null

Get the timestamp from the expiration time

Returns

int|null

getExpiry() ¶ public

getExpiry(): DateTime|DateTimeImmutable|null

Get the current expiry time

Returns

DateTime|DateTimeImmutable|null

getFormattedExpires() ¶ public

getFormattedExpires(): string

Builds the expiration value part of the header string

Returns

string

getId() ¶ public

getId(): string

Get the id for a cookie

Cookies are unique across name, domain, path tuples.

Returns

string

getName() ¶ public

getName(): string

Gets the cookie name

Returns

string

getOptions() ¶ public

getOptions(): array<string, mixed>

Get cookie options

Returns

array<string, mixed>

getPath() ¶ public

getPath(): string

Get the path attribute.

Returns

string

getSameSite() ¶ public

getSameSite(): string|null

Get the SameSite attribute.

Returns

string|null

getScalarValue() ¶ public

getScalarValue(): mixed

Gets the cookie value as scalar.

This will collapse any complex data in the cookie with json_encode()

Returns

mixed

getStringValue() ¶ public

getStringValue(): mixed

Gets the cookie value as a string.

This will collapse any complex data in the cookie with json_encode()

Returns

mixed

getValue() ¶ public

getValue(): array|string

Gets the cookie value

Returns

array|string

isExpanded() ¶ public

isExpanded(): bool

Checks if the cookie value was expanded

Returns

bool

isExpired() ¶ public

isExpired(DateTime|DateTimeImmutable $time = null): bool

Check if a cookie is expired when compared to $time

Cookies without an expiration date always return false.

Parameters

DateTime|DateTimeImmutable $time optional

Returns

bool

isHttpOnly() ¶ public

isHttpOnly(): bool

Check if the cookie is HTTP only

Returns

bool

isSecure() ¶ public

isSecure(): bool

Check if the cookie is secure

Returns

bool

read() ¶ public

read(string|null $path = null): mixed

Read data from the cookie

This method will expand serialized complex data, on first use.

Parameters

string|null $path optional: Path to read the data from

Returns

mixed

setDefaults() ¶ public static

setDefaults(array<string, mixed> $options): void

Set default options for the cookies.

Valid option keys are:

expires: Can be a UNIX timestamp or strtotime() compatible string or DateTimeInterface instance or null.
path: A path string. Defauts to '/'.
domain: Domain name string. Defaults to ''.
httponly: Boolean. Defaults to false.
secure: Boolean. Defaults to false.
samesite: Can be one of CookieInterface::SAMESITE_LAX, CookieInterface::SAMESITE_STRICT, CookieInterface::SAMESITE_NONE or null. Defaults to null.

Parameters

array<string, mixed> $options: Default options.

Returns

void

toArray() ¶ public

toArray(): array<string, mixed>

Get cookie data as array.

Returns

array<string, mixed>

toHeaderValue() ¶ public

toHeaderValue(): string

Returns a header value as string

Returns

string

validateName() ¶ protected

validateName(string $name): void

Validates the cookie name

Parameters

string $name: Name of the cookie

Returns

void

Throws

InvalidArgumentException

Links

https://tools.ietf.org/html/rfc2616#section-2.2 Rules for naming cookies.

validateSameSiteValue() ¶ protected static

validateSameSiteValue(string $sameSite): void

Check that value passed for SameSite is valid.

Parameters

string $sameSite: SameSite value

Returns

void

Throws

InvalidArgumentException

withAddedValue() ¶ public

withAddedValue(string $path, mixed $value): static

Create a new cookie with updated data.

Parameters

string $path: Path to write to
mixed $value: Value to write

Returns

static

withDomain() ¶ public

withDomain(string $domain): static

Create a cookie with an updated domain

Parameters

string $domain

Returns

static

withExpired() ¶ public

withExpired(): static

Create a new cookie that will expire/delete the cookie from the browser.

This is done by setting the expiration time to 1 year ago

Returns

static

withExpiry() ¶ public

withExpiry(DateTime|DateTimeImmutable $dateTime): static

Create a cookie with an updated expiration date

Parameters

DateTime|DateTimeImmutable $dateTime

Returns

static

withHttpOnly() ¶ public

withHttpOnly(bool $httpOnly): static

Create a cookie with HTTP Only updated

Parameters

bool $httpOnly

Returns

static

withName() ¶ public

withName(string $name): static

Sets the cookie name

Parameters

string $name

Returns

static

withNeverExpire() ¶ public

withNeverExpire(): static

Create a new cookie that will virtually never expire.

Returns

static

withPath() ¶ public

withPath(string $path): static

Create a new cookie with an updated path

Parameters

string $path

Returns

static

withSameSite() ¶ public

withSameSite(string|null $sameSite): static

Create a cookie with an updated SameSite option.

Parameters

string|null $sameSite

Returns

static

withSecure() ¶ public

withSecure(bool $secure): static

Create a cookie with Secure updated

Parameters

bool $secure

Returns

static

withValue() ¶ public

withValue(array|string $value): static

Create a cookie with an updated value.

Parameters

array|string $value

Returns

static

withoutAddedValue() ¶ public

withoutAddedValue(string $path): static

Create a new cookie without a specific path

Parameters

string $path: Path to remove

Returns

static

Property Detail

`$defaults` ¶ protected static

Default attributes for a cookie.

Type

array<string, mixed>

`$domain` ¶ protected

Domain

Type

string

`$expiresAt` ¶ protected

Expiration time

Type

DateTime|DateTimeImmutable|null

`$httpOnly` ¶ protected

HTTP only

Type

bool

`$isExpanded` ¶ protected

Whether a JSON value has been expanded into an array.

Type

bool

`$name` ¶ protected

Cookie name

Type

string

`$path` ¶ protected

Path

Type

string

`$sameSite` ¶ protected

Samesite

Type

string|null

`$secure` ¶ protected

Secure

Type

bool

`$value` ¶ protected

Raw Cookie value.

Type

array|string

Namespaces

Class Cookie

Constants

Property Summary

Method Summary

__construct() public

_expand() protected

_flatten() protected

_setValue() protected

check() public

create() public static

createFromHeaderString() public static

dateTimeInstance() protected static

getDomain() public

getExpiresTimestamp() public

getExpiry() public

getFormattedExpires() public

getId() public

getName() public

getOptions() public

getPath() public

getSameSite() public

getScalarValue() public

getStringValue() public deprecated

getValue() public

isExpanded() public

isExpired() public

isHttpOnly() public

isSecure() public

read() public

setDefaults() public static

toArray() public

toHeaderValue() public

validateName() protected

validateSameSiteValue() protected static

withAddedValue() public

withDomain() public

withExpired() public

withExpiry() public

withHttpOnly() public

withName() public

withNeverExpire() public

withPath() public

withSameSite() public

withSecure() public

withValue() public

withoutAddedValue() public

Method Detail

__construct() ¶ public

Parameters

Links

_expand() ¶ protected

Parameters

Returns

_flatten() ¶ protected

Parameters

Returns

_setValue() ¶ protected

Parameters

Returns

check() ¶ public

Parameters

Returns

create() ¶ public static

Parameters

Returns

See Also

createFromHeaderString() ¶ public static

Parameters

Returns

See Also

dateTimeInstance() ¶ protected static

Parameters

Returns

getDomain() ¶ public

Returns

getExpiresTimestamp() ¶ public

Returns

getExpiry() ¶ public

Returns