PHP class value object representing the cookie

Class, that implements HttpSoft\Cookie\CookieInterface in accordance with the RFC 6265 specification.

The HttpSoft\Cookie\Cookie object are immutable. You can use setters (with the with prefix) that return a new instance of the HttpSoft\Cookie\Cookie class with the changed data.

Source code on GitHub.

use HttpSoft\Cookie\Cookie;

$cookie = new Cookie('name', 'value', '+1 hour', '.example.com', '/path', true, true, 'Lax');

$cookie->getName(); // 'name'
$cookie->getValue(); // 'value'
$cookie->getMaxAge(); // time() + 3600
$cookie->getExpires(); // 3600
$cookie->getDomain(); // '.example.com'
$cookie->getPath(); // '/path'
$cookie->isExpired(); // false
$cookie->isSession(); // false
$cookie->isSecure(); // true
$cookie->isHttpOnly(); // true
$cookie->getSameSite(); // 'Lax'

$cookieWithNewValue = $cookie->withValue('new-value');
$cookieWithNewValue->getValue(); // 'new-value'
$cookie->getValue(); // 'value'

$cookie = $cookie->withExpires(null);
$cookie->getExpires(); // 0
$cookie->getMaxAge(); // 0
$cookie->isSession(); // true

$cookie->__toString(); // 'name=value; Domain=.example.com; Path=/path; Secure; HttpOnly; SameSite=Lax'
// equivalently to:
(string) $cookie;

# Public methods

See the original detailed description of the methods in the HttpSoft\Cookie\CookieInterface.

/**
 * @param string $name the name of the cookie.
 * @param string $value the value of the cookie.
 * @param DateTimeInterface|int|string|null $expire the time the cookie expire.
 * @param string|null $path the set of paths for the cookie.
 * @param string|null $domain the set of domains for the cookie.
 * @param bool|null $secure whether the cookie should only be transmitted over a secure HTTPS connection.
 * @param bool|null $httpOnly whether the cookie can be accessed only through the HTTP protocol.
 * @param string|null $sameSite whether the cookie will be available for cross-site requests.
 * @throws InvalidArgumentException if one or more arguments are not valid.
 */
public function __construct(
    string $name,
    string $value = '',
    $expire = null,
    ?string $domain = null,
    ?string $path = '/',
    ?bool $secure = true,
    ?bool $httpOnly = true,
    ?string $sameSite = self::SAME_SITE_LAX
);

# __toString

Returns a string representation of the cookie.

public function __toString(): string;

String representation as raw value of the Set Cookie header.

$cookie = new Cookie('name', 'value');

$cookie->__toString(); // 'name=value; Path=/path; Secure; HttpOnly; SameSite=Lax'
(string) $cookie; // 'name=value; Path=/path; Secure; HttpOnly; SameSite=Lax'
echo $cookie; // 'name=value; Path=/path; Secure; HttpOnly; SameSite=Lax'

# getName

Gets the name of the cookie.

public function getName(): string;

# getValue

Gets the value of the cookie.

public function getValue(): string;

# withValue

Returns a new HttpSoft\Cookie\Cookie instance with the specified value.

public function withValue(string $value): self;

$cookie = new Cookie('name', 'value');

$new = $cookie->withValue('new-value');
$new->getValue(); // 'new-value'
$cookie->getValue(); // 'value'

# getMaxAge

Gets the max-age attribute.

public function getMaxAge(): int;

# getExpires

Gets the time the cookie expires.

public function getExpires(): int;

# isExpired

Checks whether this cookie is expired.

public function isExpired(): bool;

If a cookie is a session cookie, it is not considered expired.

# isSession

Checks whether this cookie is a session cookie.

public function isSession(): bool;

# expire

Returns a new HttpSoft\Cookie\Cookie instance that will expire immediately.

public function expire(): self;

$cookie = new Cookie('name', 'value', '+1 hour');
$cookie->getExpires(); // time() + 3600
$cookie->getMaxAge(); // 3600

$new = $cookie->expire();
$new->getExpires(); // time() - 31536001
$cookie->getMaxAge(); // 0

# withExpires

Returns a new HttpSoft\Cookie\Cookie instance with the specified time expire.

public function withExpires($expire = null): self;

The $expire value can be an DateTimeInterface instance, a string representation of a date, or an integer Unix timestamp, or null.

$cookie = new Cookie('name', 'value');

$new = $cookie->withExpires('+1 hour');
// equivalently to
$new = $cookie->withExpires(time() + 3600);
// equivalently to
$new = $cookie->withExpires(new DateTimeImmutable('+1 hour'));

$new->getExpires(); // time() + 3600
$cookie->getExpires(); // 0

$new->getMaxAge(); // 3600
$cookie->getMaxAge(); // 0

If the $expire was not specified or has an empty value, the cookie will be converted to a session cookie, which will expire as soon as the browser is closed.

$cookie = new Cookie('name', 'value', '+1 hour');

$new = $cookie->withExpires(null);
// equivalently to
$new = $cookie->withExpires(0);
// equivalently to
$new = $cookie->withExpires('');

$new->getExpires(); // 0
$cookie->getExpires(); // time() + 3600

$new->getMaxAge(); // 0
$cookie->getMaxAge(); // 3600

$new->isSession(); // true
$cookie->isSession(); // false

If $expire is invalid, the \InvalidArgumentException exception will be thrown.

$cookie->withExpires(1.1); // throws InvalidArgumentException
$cookie->withExpires(new StdClass); // throws InvalidArgumentException
$cookie->withExpires('invalid-string'); // throws InvalidArgumentException

# getDomain

Gets cookie domains, or null if they are not specified.

public function getDomain(): ?string;

# withDomain

Returns a new HttpSoft\Cookie\Cookie instance with the specified domains.

public function withDomain(?string $domain): self;

$cookie->getDomain(); // null
$new = $cookie->withDomain('.example.com');

$new->getDomain(); // '.example.com'
$cookie->getDomain(); // null

# getPath

Gets cookie paths, or null if they are not specified.

public function getPath(): ?string;

# withPath

Returns a new HttpSoft\Cookie\Cookie instance with the specified paths.

public function withPath(?string $path): self;

$cookie->getPath(); // '/'
$new = $cookie->withPath('/path');

$new->getPath(); // '/path'
$cookie->getPath(); // '/'

# isSecure

Checks whether the cookie should only be transmitted over a secure HTTPS connection.

public function isSecure(): bool;

# withSecure

Returns a new HttpSoft\Cookie\Cookie instance with the specified enabling or disabling cookie transmission over a secure HTTPS connection.

public function withSecure(bool $secure = true): self;

$cookie->isSecure(); // false

$secure = $cookie->withSecure();
// equivalently to
$secure = $cookie->withSecure(true);

$secure->isSecure(); // true
$cookie->isSecure(); // false

$notSecure = $secure->withSecure(false);
$notSecure->isSecure(); // false

# isHttpOnly

Checks whether the cookie can be accessed only through the HTTP protocol.

public function isHttpOnly(): bool;

# withHttpOnly

Returns a new HttpSoft\Cookie\Cookie instance with the specified enabling or disabling cookie transmission over the HTTP protocol only.

public function withHttpOnly(bool $httpOnly = true): self;

$cookie->isHttpOnly(); // false

$httpOnly = $cookie->withHttpOnly();
// equivalently to
$httpOnly = $cookie->withHttpOnly(true);

$httpOnly->isHttpOnly(); // true
$cookie->isHttpOnly(); // false

$notHttpOnly = $httpOnly->withHttpOnly(false);
$notHttpOnly->isHttpOnly(); // false

# getSameSite

Gets the SameSite attribute. By default, 'Lax'.

public function getSameSite(): ?string;

# withSameSite

Returns a new HttpSoft\Cookie\Cookie instance with the specified SameSite attribute.

public function withSameSite(?string $sameSite): self;

Supported SameSite attribute values: 'None', 'Lax', 'Strict' and null.

Any other value will cause an \InvalidArgumentException exception.

$cookie->getSameSite(); // 'Lax'

$cookie = $cookie->withSameSite('strict');
$cookie->getSameSite(); // 'Strict'

$cookie = $cookie->withSameSite('NONE');
$cookie->getSameSite(); // 'None'

$cookie = $cookie->withSameSite(null);
$cookie->getSameSite(); // null

$cookie->withSameSite('unsupported-value'); // throws InvalidArgumentException

See the Set-Cookie header for details on attributes.

# Class HttpSoft\Cookie\Cookie