Click the Castor logo or press Ctrl Alt T to change theme.
# Cookies Castor HTTP provides two cookie types: - `Castor\Net\Http\Cookie` represents a single RFC 6265 cookie. - `Castor\Net\Http\Cookies` is an indexed collection of `Cookie` objects. Cookies are deliberately separate from `Request` and `Response`. The raw messages only contain headers; you parse cookies from those headers when you need them. ## A single cookie ```php <?php use Castor\Net\Http\Cookie; use Castor\Net\Http\SameSite; $cookie = new Cookie( name: 'session', value: 'abc123', path: '/', domain: 'example.com', expires: new DateTimeImmutable('+1 hour'), secure: true, httpOnly: true, sameSite: SameSite::Lax, ); ``` A `Cookie` exposes these public fields: | Field | Meaning | | --- | --- | | `name` | Cookie name. An empty name serializes to an empty string. | | `value` | Cookie value. | | `path` | Optional `Path` attribute for `Set-Cookie`. | | `domain` | Optional `Domain` attribute for `Set-Cookie`. | | `expires` | Optional `DateTimeImmutable` expiry. | | `maxAge` | Optional `Max-Age`; `0` means omitted. | | `secure` | Whether to emit `Secure`. | | `httpOnly` | Whether to emit `HttpOnly`. | | `sameSite` | Optional `SameSite::Lax`, `Strict`, or `None`. | ## Cookie header serialization The `Cookie` request header uses only name and value: ```php $cookie = new Cookie('theme', 'dark'); $cookie->toCookieString(); // "theme=dark" ``` Names and values are URL-encoded when serialized. A cookie with an empty name serializes to an empty string. ## Set-Cookie serialization The `Set-Cookie` response header includes attributes: ```php $cookie = new Cookie( name: 'session', value: 'abc123', path: '/', secure: true, httpOnly: true, sameSite: SameSite::Lax, ); echo $cookie->toSetCookieString(); // session=abc123; Path=/; Secure; HttpOnly; SameSite=Lax ``` `expires` is formatted in UTC using the standard cookie date format: `D, d M Y H:i:s T`. ## Expiring and remembering cookies ```php $cookie->expire(); $cookie->rememberForever(); ``` `expire` sets the expiry to five years in the past and clears `Max-Age`. `rememberForever` sets the expiry to five years in the future and also clears `Max-Age`. ## Parsing Cookie headers Parse a request `Cookie` header with `Cookies::fromCookieHeader`: ```php <?php use Castor\Net\Http\Cookies; $cookies = Cookies::fromCookieHeader($request->headers); $session = $cookies->lookup('session'); // Cookie|null $theme = $cookies->get('theme'); // Cookie, even when absent ``` `lookup` returns `null` when the cookie is absent. `get` returns a new empty cookie with the requested name when it is absent; that fallback cookie is not inserted into the collection. For lower-level parsing, use `Cookie::fromCookieString` or `Cookie::fromCookiePair`. ## Parsing Set-Cookie headers Parse response cookies with `Cookies::fromSetCookieHeader`: ```php $cookies = Cookies::fromSetCookieHeader($response->headers); ``` `Cookie::fromSetCookieString` parses a single header value. Malformed cookie headers produce an empty cookie instead of throwing. Invalid `Expires` dates and invalid `SameSite` values are silently skipped. ## Cookie collections Create a collection explicitly: ```php $cookies = Cookies::create( new Cookie('session', 'abc123'), new Cookie('theme', 'dark'), ); ``` The collection is keyed by cookie name: ```php $cookies->has('session'); // true $cookies->lookup('session'); // Cookie|null $cookies->toArray(); // list of Cookie objects count($cookies); // Countable ``` `with` and `without` return modified copies of the collection: ```php $withLocale = $cookies->with(new Cookie('locale', 'en')); $withoutTheme = $cookies->without('theme'); ``` The collection object is copied, but the `Cookie` instances themselves are mutable values. Use `Cookie::copy()` if you need an independent cookie object before mutating it. ## Writing cookies to headers Write request cookies into the `Cookie` header: ```php $cookies->writeCookie($request->headers); ``` This creates a single semicolon-separated `Cookie` header and ignores cookies without a name. Write response cookies into `Set-Cookie` headers: ```php $cookies->writeSetCookie($response->headers); ``` `writeSetCookie` removes all existing `Set-Cookie` values first, then writes the collection. To append or replace one cookie without clearing others, use the helper function: ```php <?php use Castor\Net\Http; Http\setCookie($writer->headers(), new Cookie('session', 'abc123', path: '/')); ``` `setCookie` silently drops cookies that serialize to an empty string.
Castor ecosystem