nolikein / cookie-interface
A library which provides an interface to create cookies. Inspired by PSR practices : https://www.php-fig.org/psr/
Requires
- php: ^8.4
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.95
- pestphp/pest: ^4.0
- phpstan/phpstan: ^2.3
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
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, likesetcookie) and its SameSite is'Lax'. withNametakes a non-empty RFC 6265 token: US-ASCII, without control character, whitespace or( ) < > @ , ; : \ " / [ ] ? = { }.withValuestores the value as given andgetValue()returns it unchanged. Whoever builds theSet-Cookieheader MUST encode it (assetcookiedoes) or refuse it, otherwise a value such asx; Domain=evil.exampleinjects an attribute.withExpirationTimetakes a Unix timestamp (int) or aDateTimeInterface. A timestamp of0means a session cookie:getExpirationTime()returnsnullandisExpired()returnsfalse.withPathadds 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, passfalseto allow scripts to read it.withSameSiteaccepts'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 sendSameSite=NonewithoutSecure.
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.