nolikein / cookie-manager
A library which provides a cookie, a factory to create it and a facade to set or unset it. Inspired by PSR practices : https://www.php-fig.org/psr/
Requires
- php: ^8.4
- nolikein/cookie-factory-interface: ^2.0
- nolikein/cookie-interface: ^2.1
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.95
- pestphp/pest: ^4
- phpstan/phpstan: ^2.3
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-11 21:33:31 UTC
README
cookie-manager
Overview
Managing cookies may be difficult without any constraint. So, in the spirit of the PSR (PHP Standards Recommendations) I created an interface named CookieInterface.
The generic nature of this interface allows a design pattern named factory. This library provides a Cookie which implements the interface, a factory to create it, and a facade to set or unset it with the native setcookie() function.
Requirements
PHP 8.4 or later.
Installation
composer require nolikein/cookie-manager ^2.0
Usage
You can create a cookie manually with the Cookie class, create easily a cookie by using CookieFactory, or set/unset a cookie by giving an object implementing CookieInterface to CookieFacade.
CookieFactory - The easy way
use Nolikein\Cookie\CookieFactory;
$factory = new CookieFactory();
$cookie = $factory->createCookie('name', 'value');
$cookie = $factory->createCookie('name', 'value', time() + 3600, '/my/path', 'www.mywebsite.org', true, false);
$cookie = $factory->createCookie(
'name',
'value',
(new \DateTimeImmutable('now'))->add(new \DateInterval('P1D')),
'/my/path',
'www.mywebsite.org',
true,
false,
);
The arguments are the name, the value, the expiration time (a Unix timestamp or a DateTimeInterface, 0 for a session cookie), the path, the domain, isSecure and isHttpOnly. A cookie is HTTP only by default: pass false as the last argument to let scripts read it.
CookieFacade - Set/unset a cookie
use Nolikein\Cookie\CookieFacade;
$cookie = // Define a CookieInterface object
$facade = new CookieFacade();
$facade->setCookie($cookie);
$facade->unsetCookie($cookie);
Both methods return the result of setcookie(): false when the headers are already sent. unsetCookie() repeats the path, the domain and the flags of the cookie, because a browser only deletes a cookie whose path and domain match.
A cookie with the SameSite value None must be secure: browsers refuse SameSite=None without Secure, so both methods throw CannotSetCookie instead of sending it.
Cookie - The hard way
A cookie object implements the CookieInterface. It has these attributes:
- name (an RFC 6265 token)
- value (stored as it is given;
setcookie()encodes it when it is sent) - expirationTime (either an int timestamp or a
DateTimeInterface;0is a session cookie) - path
- domain
- isSecure (is https ?)
- isHttpOnly (is only accessible by http, and not for script languages ?)
- sameSite (
None,LaxorStrict, in any case;Laxby default)
So, the object has 'withSomething' and 'getSomething' methods. Note: All with methods return a copy of the current instance, and the expiration time it returns cannot change the cookie.
To know if a cookie has expired you can use the $cookie->isExpired() method.
Exceptions
A refused value throws an exception of the Nolikein\Cookie\Exceptions namespace. Each one extends \InvalidArgumentException and implements Nolikein\Cookie\CookieExceptionInterface, so one catch handles any refused value:
| Exception | Thrown when |
|---|---|
InvalidName | The name is empty or is not an RFC 6265 token |
InvalidPath | The path holds a control character, a whitespace, a non US-ASCII character, ; or , |
InvalidDomain | The domain holds such a character, or is not a valid host name (an IP address and a leading dot are refused: use the empty domain for a host-only cookie) |
InvalidSameSite | The SameSite value is not None, Lax or Strict |
CannotSetCookie (a \RuntimeException which also implements CookieExceptionInterface) is thrown by CookieFacade for a SameSite=None cookie that is not secure. A value of the wrong type is a TypeError.
Development
Every PHP, Composer and vendor/bin command runs in the Docker container:
docker compose run --rm php composer install
docker compose run --rm php composer qa # format check, PHPStan and the Pest tests
PHP_VERSION=8.5 docker compose run --rm php composer qa