PHP-Cookie

by delight-im

delight-im / PHP-Cookie

Modern cookie management for PHP

139 Stars 41 Forks Last release: Not found MIT License 100 Commits 20 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

PHP-Cookie

Modern cookie management for PHP

Requirements

  • PHP 5.4.0+

Installation

  1. Include the library via Composer [?]:

    $ composer require delight-im/cookie
    
  2. Include the Composer autoloader:

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

Upgrading

Migrating from an earlier version of this project? See our upgrade guide for help.

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:
\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.
$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:

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

A cookie can later be deleted simply like this:

$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.

Reading cookies

  • Checking whether a cookie exists:
   \Delight\Cookie\Cookie::exists('first_visit');
  • Reading a cookie’s value (with optional default value):
   \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:
// 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
.

Likewise, replacements for

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

are available via

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

if you want protection against session fixation attacks that comes with improved cookie handling.

Additionally, access to the current internal session ID is provided via

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

as a replacement for

session_id();

Reading and writing session data

  • Read a value from the session (with optional default value):
   $value = \Delight\Cookie\Session::get($key);
   // or
   $value = \Delight\Cookie\Session::get($key, $defaultValue);
  • Write a value to the session:
   \Delight\Cookie\Session::set($key, $value);
  • Check whether a value exists in the session:
   if (\Delight\Cookie\Session::has($key)) {
       // ...
   }
  • Remove a value from the session:
   \Delight\Cookie\Session::delete($key);
  • Read and then immediately remove a value from the session:
   $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.

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

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.

License

This project is licensed under the terms of the MIT License.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.