Reading cookies tells us what the browser sent with the current request. Setting and deleting cookies tells the browser what it should store for future requests.

In PHP, that happens through HTTP headers. CookieHandler calls PHP’s setcookie() function for us, but the same rule still applies: headers must be sent before the response body starts.

¶Setting a cookie

Use set() with a name, value, and optional expiry:

use GT\Cookie\CookieHandler;

$cookies = new CookieHandler($_COOKIE);

$cookies->set(
	"seenWelcome",
	"yes",
	new DateTime("+30 days"),
);

After this call, two things have happened:

• the handler contains a Cookie object for seenWelcome
• PHP has been asked to send a Set-Cookie header to the browser

¶Expiry

The third argument accepts any DateTimeInterface:

$cookies->set("promo", "spring", new DateTime("2026-05-01 00:00:00"));

For persistent cookies, always pass an explicit future expiry date.

If the expiry argument is omitted, the current implementation sends the current timestamp to setcookie(). That is usually not what we want for a long-lived preference cookie, so examples in this guide pass the expiry explicitly.

¶Domain, secure, and HTTP-only flags

set() also accepts a domain, secure flag, and HTTP-only flag:

$cookies->set(
	"rememberDevice",
	"1",
	new DateTime("+90 days"),
	domain: "example.com",
	secure: true,
	httponly: true,
);

The cookie path is always sent as /.

secure: true tells the browser to send the cookie only over HTTPS. httponly: true tells the browser not to expose the cookie to JavaScript through document.cookie.

[!TIP] For authentication or other sensitive server-side state, store the real data in a session or database and use the cookie only as an identifier. Cookies are sent by the browser and should not be treated as private storage.

¶Why array assignment is blocked

This works for reading:

echo $cookies["theme"];

But this does not work for writing:

$cookies["theme"] = "dark";

Array assignment throws CookieSetException. Setting a cookie needs more information than a value alone, such as expiry and security flags, so the library requires us to call set() explicitly.

¶Deleting one cookie

Use delete() when the browser should forget a cookie:

$cookies->delete("theme");

The cookie is removed from the handler immediately. The browser receives an expired cookie with the same name and the path /.

Array unset uses the same behaviour:

unset($cookies["theme"]);

¶Clearing several cookies

Use clear() with one or more names:

$cookies->clear("theme", "currency");

Each named cookie is set to an empty value with an expiry in the past, then removed from the handler.

¶Clearing every tracked cookie

Call clear() without arguments:

$cookies->clear();

This clears every cookie currently stored in the handler.

[!IMPORTANT] Browsers match cookies by name, domain, and path. This library deletes cookies using the path /. If a cookie was created by other code with a different path or domain, that other code may need to delete it with the same attributes.

---

Next, see Cookie objects and validation to understand the immutable value objects stored by the handler.