delight-im/cookie

Modern cookie management for PHP

PHP-Cookie

Modern cookie management for PHP, _(*1)

Requirements

• PHP 5.4.0+

Installation

1. Include the library via Composer [?]:, _(*2)

   $ composer require delight-im/cookie
   

2. Include the Composer autoloader:, _(*3)

   require __DIR__ . '/vendor/autoload.php';
   

Upgrading

Migrating from an earlier version of this project? See our upgrade guide for help., _(*4)

Usage

Static method

This library provides a static method that is compatible to PHP’s built-in setcookie(...) function but includes support for more recent features such as the SameSite attribute:, _(*5)

\Delight\Cookie\Cookie::setcookie('SID', '31d4d96e407aad42');
// or
\Delight\Cookie\Cookie::setcookie('SID', '31d4d96e407aad42', time() + 3600, '/~rasmus/', 'example.com', true, true, 'Lax');

Builder pattern

Instances of the Cookie class let you build a cookie conveniently by setting individual properties. This class uses reasonable defaults that may differ from defaults of the setcookie function., _(*6)

$cookie = new \Delight\Cookie\Cookie('SID');
$cookie->setValue('31d4d96e407aad42');
$cookie->setMaxAge(60 * 60 * 24);
// $cookie->setExpiryTime(time() + 60 * 60 * 24);
$cookie->setPath('/~rasmus/');
$cookie->setDomain('example.com');
$cookie->setHttpOnly(true);
$cookie->setSecureOnly(true);
$cookie->setSameSiteRestriction('Strict');

// echo $cookie;
// or
$cookie->save();
// or
// $cookie->saveAndSet();

The method calls can also be chained:, _(*7)

(new \Delight\Cookie\Cookie('SID'))->setValue('31d4d96e407aad42')->setMaxAge(60 * 60 * 24)->setSameSiteRestriction('None')->save();

A cookie can later be deleted simply like this:, _(*8)

$cookie->delete();
// or
$cookie->deleteAndUnset();

Note: For the deletion to work, the cookie must have the same settings as the cookie that was originally saved – except for its value, which doesn’t need to be set. So you should remember to pass appropriate values to setPath(...), setDomain(...), setHttpOnly(...) and setSecureOnly(...) again., _(*9)

Reading cookies

• Checking whether a cookie exists:, _(*10)

  \Delight\Cookie\Cookie::exists('first_visit');
  

• Reading a cookie’s value (with optional default value):, _(*11)

  \Delight\Cookie\Cookie::get('first_visit');
  // or
  \Delight\Cookie\Cookie::get('first_visit', \time());
  

Managing sessions

Using the Session class, you can start and resume sessions in a way that is compatible to PHP’s built-in session_start() function, while having access to the improved cookie handling from this library as well:, _(*12)

// start session and have session cookie with 'lax' same-site restriction
\Delight\Cookie\Session::start();
// or
\Delight\Cookie\Session::start('Lax');

// start session and have session cookie with 'strict' same-site restriction
\Delight\Cookie\Session::start('Strict');

// start session and have session cookie without any same-site restriction
\Delight\Cookie\Session::start(null);
// or
\Delight\Cookie\Session::start('None'); // Chrome 80+

All three calls respect the settings from PHP’s session_set_cookie_params(...) function and the configuration options session.name, session.cookie_lifetime, session.cookie_path, session.cookie_domain, session.cookie_secure, session.cookie_httponly and session.use_cookies., _(*13)

Likewise, replacements for, _(*14)

session_regenerate_id();
// and
session_regenerate_id(true);

are available via, _(*15)

\Delight\Cookie\Session::regenerate();
// and
\Delight\Cookie\Session::regenerate(true);

if you want protection against session fixation attacks that comes with improved cookie handling., _(*16)

Additionally, access to the current internal session ID is provided via, _(*17)

\Delight\Cookie\Session::id();

as a replacement for, _(*18)

session_id();

Reading and writing session data

• Read a value from the session (with optional default value):, _(*19)

  $value = \Delight\Cookie\Session::get($key);
  // or
  $value = \Delight\Cookie\Session::get($key, $defaultValue);
  

• Write a value to the session:, _(*20)

  \Delight\Cookie\Session::set($key, $value);
  

• Check whether a value exists in the session:, _(*21)

  if (\Delight\Cookie\Session::has($key)) {
     // ...
  }
  

• Remove a value from the session:, _(*22)

  \Delight\Cookie\Session::delete($key);
  

• Read and then immediately remove a value from the session:, _(*23)

  $value = \Delight\Cookie\Session::take($key);
  $value = \Delight\Cookie\Session::take($key, $defaultValue);
  

  This is often useful for flash messages, e.g. in combination with the has(...) method., _(*24)

Parsing cookies

$cookieHeader = 'Set-Cookie: test=php.net; expires=Thu, 09-Jun-2016 16:30:32 GMT; Max-Age=3600; path=/~rasmus/; secure';
$cookieInstance = \Delight\Cookie\Cookie::parse($cookieHeader);

Specifications

• RFC 2109
• RFC 6265
• Same-site Cookies (formerly 2016-06-20 and 2016-04-06)
  • Amendment: Default to Lax and require secure attribute for None (Note: There are incompatible clients)

Contributing

All contributions are welcome! If you wish to contribute, please create an issue first so that your feature, problem or question can be discussed., _(*25)

License

This project is licensed under the terms of the MIT License., _(*26)