Documentation menu
On this page

Components · v1.x

Cookie

The Cookie component reads the cookies of the request and queues new cookies, optionally signed with APP_SECRET. Queued cookies are added to the response automatically.

Usage

In a controller, getCookies() returns the CookieInterface service:

$cookies = $this->getCookies();

$cookies->set('theme', 'dark', ['lifetime' => 3600 * 24 * 30]);
$cookies->set('remember', 'user-42', ['signed' => true]);
$cookies->remove('theme');

$theme = $cookies->get('theme', 'light');
$user = $cookies->getSigned('remember');

Outside controllers, inject NeoPHP\Component\Cookie\Contract\CookieInterface. Cookies set during the request are added to the response by CookieListener (on ResponseEvent, priority -100).

Options

Option Default Description
lifetime 0 seconds; 0 is a session cookie
path / cookie path
domain null cookie domain
secure auto auto follows the request (HTTPS), or true / false
httponly true hides the cookie from JavaScript
samesite Lax Lax, Strict, None or ''
signed false signs the value with APP_SECRET (HMAC SHA-256)

Options passed to set() / remove() override the values of config/framework/app.yaml.

Signed cookies

getSigned() returns the value only when its signature is valid: a cookie modified by the client returns the default value. get() returns the raw value. Signing needs APP_SECRET (framework.app.secret, generated by neo install); without it a CookieException is thrown.

Configuration

config/framework/app.yaml:

secret: '%env(APP_SECRET)%'

cookie:
  lifetime: 0
  path: /
  domain: ~
  secure: auto
  httponly: true
  samesite: Lax

framework.app.cookie holds the default options, framework.app.secret the signing key.

In templates

cookie($name, $default = null, $signed = false):

<body class="theme-{{ cookie('theme', 'light') }}">

<body class="theme-<?= $this->e($this->cookie('theme', 'light')) ?>">

PHP API

NeoPHP\Component\Cookie\Contract\CookieInterface (implemented by CookieManager):

Method Description
get(string $name, mixed $default = null): mixed raw value (a queued value wins over the request)
getSigned(string $name, mixed $default = null): mixed value when the signature is valid
has(string $name): bool whether the cookie exists (request or queue)
all(): array every cookie, queued values included
set(string $name, string $value, array $options = []): static queues a cookie
remove(string $name, array $options = []): static queues the expiration of a cookie
getQueued(): array queued cookies with their options
apply(Response $response): Response adds the queued cookies to a response

new CookieManager(array $cookies = [], array $defaults = [], ?string $secret = null, bool $secureRequest = false) builds a standalone instance.

Exceptions

NeoPHP\Component\Cookie\Exception\CookieException is thrown for a signed cookie without secret or an invalid option (such as an unknown samesite).

Changelog

  • v1.6.0 — Cookie component: cookies read from the request, queued and signed with APP_SECRET, getCookies() controller trait, cookie() view helper, configuration in app.yaml.