Search by

nolikein / cookie-interface

Nolikein

A library which provides an interface to create cookies. Inspired by PSR practices : https://www.php-fig.org/psr/

2.1.0 2026-11-08 23:43 UTC

This package is auto-updated.

Last update: 2026-11-11 21:33:39 UTC


README

PHP Packagist version Downloads Packagist License Pipeline

Overview

Managing cookies may be difficult without any constraint. So, in the spirit of the PSR (PHP Standards Recommendations) I created this interface. It describes everything you need to create a cookie class: an immutable object whose properties map onto the parameters of the native setcookie function.

Requirements

PHP 8.4 or later.

Installation

composer require nolikein/cookie-interface ^2.0

Usage

Create a class which implements Nolikein\Cookie\CookieInterface: it declares the 16 methods of the contract (withName, withValue, withExpirationTime, withPath, withDomain, withSecurity, withSameSite and their getters). A complete implementation is available in tests/Helpers/reference_cookie.php (it is not part of the Composer package).

Any implementation can then be used like this:

use Nolikein\Cookie\CookieInterface;

function prepareSessionCookie(CookieInterface $cookie): CookieInterface
{
    return $cookie
        ->withName('session')
        ->withValue('abc123')
        ->withExpirationTime(time() + 3600)
        ->withPath('/')
        ->withSecurity(true, true)
        ->withSameSite('Lax');
}

The contract in short:

  • Every with* method returns a modified copy and leaves the original untouched.
  • A new cookie is neither secure nor HTTP only (false, like setcookie) and its SameSite is 'Lax'.
  • withName takes a non-empty RFC 6265 token: US-ASCII, without control character, whitespace or ( ) < > @ , ; : \ " / [ ] ? = { }.
  • withValue stores the value as given and getValue() returns it unchanged. Whoever builds the Set-Cookie header MUST encode it (as setcookie does) or refuse it, otherwise a value such as x; Domain=evil.example injects an attribute.
  • withExpirationTime takes a Unix timestamp (int) or a DateTimeInterface. A timestamp of 0 means a session cookie: getExpirationTime() returns null and isExpired() returns false.
  • withPath adds the leading / to a non-empty path when it is missing; an empty path stays empty (the default path). A path limits where the browser sends the cookie, it is not a security boundary.
  • withDomain: an empty domain is a host-only cookie, the narrowest scope; a non-empty domain also covers every subdomain.
  • withSecurity($isSecure, $isHttpOnly = true) replaces both flags: withSecurity(true) makes the cookie HTTP only, pass false to allow scripts to read it.
  • withSameSite accepts 'None', 'Lax' or 'Strict', in any case; getSameSite() returns the canonical case. A cookie with 'None' SHOULD be secure, and whoever emits it MUST NOT send SameSite=None without Secure.

Exceptions

A value refused by withName, withPath, withDomain or withSameSite makes the implementation throw: it never trims, strips or replaces characters silently. The exception MUST extend \InvalidArgumentException and implement Nolikein\Cookie\CookieExceptionInterface, so one catch handles any refused value:

use Nolikein\Cookie\CookieExceptionInterface;

try {
    $cookie = $cookie->withName($name);
} catch (CookieExceptionInterface $exception) {
    // the name was refused
}

This package ships no exception class: an implementation writes its own, for example class InvalidCookieArgument extends \InvalidArgumentException implements CookieExceptionInterface {}. A TypeError raised by a native parameter type (withExpirationTime) is not covered.

The message of the exception MUST NOT contain the value of the cookie, which may be a session id and would reach the logs: name the refused attribute ("The value MUST NOT contain a control character."), never the value itself.

Development

Every command runs in the Docker container, never on the host. The default PHP version is 8.4; set PHP_VERSION=8.5 to use another one.

docker compose build
docker compose run --rm php composer install
docker compose run --rm php composer qa

composer qa runs the format check, PHPStan and the Pest tests.

Links