# Class HttpSoft\Cookie\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 thewith
prefix) that return a new instance of theHttpSoft\Cookie\Cookie
class with the changed data.
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.