Search by

nolikein / cookie-manager

Nolikein

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/

2.0.0 2026-11-09 00:25 UTC

This package is auto-updated.

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


README

cookie-manager

PHP Packagist version Downloads License Pipeline Coverage

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; 0 is a session cookie)
  • path
  • domain
  • isSecure (is https ?)
  • isHttpOnly (is only accessible by http, and not for script languages ?)
  • sameSite (None, Lax or Strict, in any case; Lax by 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:

ExceptionThrown when
InvalidNameThe name is empty or is not an RFC 6265 token
InvalidPathThe path holds a control character, a whitespace, a non US-ASCII character, ; or ,
InvalidDomainThe 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)
InvalidSameSiteThe 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

Links