# Класс HttpSoft\Cookie\Cookie

Класс, реализующий HttpSoft\Cookie\CookieInterface в соответствии со спецификацией RFC 6265.

Объект HttpSoft\Cookie\Cookie является неизменяемым. Вы можете использовать сеттеры (с префиксом with), которые возвращают новый экземпляр класса HttpSoft\Cookie\Cookie с измененными данными.

Исходный код на 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'
// эквивалентно:
(string) $cookie;

# Публичные методы

Оригинальное подробное описание методов смотрите в HttpSoft\Cookie\CookieInterface.

/**
 * @param string $name имя куки.
 * @param string $value значение куки.
 * @param DateTimeInterface|int|string|null $expire время истечения срока действия куки.
 * @param string|null $path набор путей для куки.
 * @param string|null $domain набор доменов для куки.
 * @param bool|null $secure следует ли передавать куку только через безопасное соединение HTTPS.
 * @param bool|null $httpOnly можно ли получить доступ к куке только через HTTP-протокол.
 * @param string|null $sameSite будет ли кука доступна для кроссдоменных запросов.
 * @throws InvalidArgumentException если один или несколько аргументов невалидны.
 */
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

Возвращает строковое представление куки.

public function __toString(): string;

Строковое представление в виде необработанного значения заголовка Set-Cookie.

$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

Возвращает имя куки.

public function getName(): string;

# getValue

Возвращает значение куки.

public function getValue(): string;

# withValue

Возвращает новый экземпляр HttpSoft\Cookie\Cookie с указанным значением.

public function withValue(string $value): self;
$cookie = new Cookie('name', 'value');

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

# getMaxAge

Возвращает атрибут max-age.

public function getMaxAge(): int;

# getExpires

Возвращает время истечения срока действия куки.

public function getExpires(): int;

# isExpired

Проверяет, не истек ли срок действия куки.

public function isExpired(): bool;

Если кука является сессионной, то она не считается истекшей.

# isSession

Проверяет, является ли данная кука сессионной.

public function isSession(): bool;

# expire

Возвращает новый экземпляр HttpSoft\Cookie\Cookie, срок действия которого истекает немедленно.

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

Возвращает новый экземпляр HttpSoft\Cookie\Cookie с указанным временем истечения срока действия.

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

Значение $expire может быть экземпляром DateTimeInterface, строковым представлением даты, целочисленной меткой времени Unix или null.

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

$new = $cookie->withExpires('+1 hour');
// эквивалентно
$new = $cookie->withExpires(time() + 3600);
// эквивалентно
$new = $cookie->withExpires(new DateTimeImmutable('+1 hour'));

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

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

Если параметр $expire не был указан или имеет пустое значение, кука будет преобразована в сессионную, срок действия которой истечет сразу после закрытия браузера.

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

$new = $cookie->withExpires(null);
// эквивалентно
$new = $cookie->withExpires(0);
// эквивалентно
$new = $cookie->withExpires('');

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

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

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

Если $expire невалидный, будет брошено исключение \InvalidArgumentException.

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

# getDomain

Возвращает домены куки или null, если они не заданы.

public function getDomain(): ?string;

# withDomain

Возвращает новый экземпляр HttpSoft\Cookie\Cookie с указанными доменами.

public function withDomain(?string $domain): self;
$cookie->getDomain(); // null
$new = $cookie->withDomain('.example.com');

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

# getPath

Возвращает пути куки или null, если они не заданы.

public function getPath(): ?string;

# withPath

Возвращает новый экземпляр HttpSoft\Cookie\Cookie с указанными путями.

public function withPath(?string $path): self;
$cookie->getPath(); // '/'
$new = $cookie->withPath('/path');

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

# isSecure

Проверяет, следует ли передавать куку только по защищенному HTTPS-соединению.

public function isSecure(): bool;

# withSecure

Возвращает новый экземпляр HttpSoft\Cookie\Cookie с указанным включением или отключением передачи куки по защищенному HTTPS-соединению.

public function withSecure(bool $secure = true): self;
$cookie->isSecure(); // false

$secure = $cookie->withSecure();
// эквивалентно
$secure = $cookie->withSecure(true);

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

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

# isHttpOnly

Проверяет, можно ли получить доступ к куки только по HTTP-протоколу.

public function isHttpOnly(): bool;

# withHttpOnly

Возвращает новый экземпляр HttpSoft\Cookie\Cookie с указанным включением или отключением передачи куки только по HTTP-протоколу.

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

Возвращает атрибут SameSite, по умолчанию 'Lax'.

public function getSameSite(): ?string;

# withSameSite

Возвращает новый экземпляр HttpSoft\Cookie\Cookie с указанным атрибутом SameSite.

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

Поддерживаемые значения SameSite атрибута: 'None', 'Lax', 'Strict' and null.

Любое другое значение вызовет исключение \InvalidArgumentException.

$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

Подробнее об атрибутах смотрите в описании заголовка Set-Cookie.