PHP-Cookie
This is a PHP7-only fork of Delight IM's Cookie library
which uses the maximum level of security by default., (*1)
This means:, (*2)
- Secure is set to
TRUE unless you override it.
- HTTP-Only is set to
TRUE unless you override it.
- Same-Site is set to
Strict unless you override it.
Modern cookie management for PHP, (*3)
Requirements
Installation
-
Install via Composer (recommended), (*4)
$ composer require paragonie/cookie, (*5)
Include the Composer autoloader:, (*6)
require __DIR__.'/vendor/autoload.php';, (*7)
-
or, (*8)
-
Install manually, (*9)
- Copy the contents of the
src directory to a subfolder of your project
- Include the files in your code via
require or require_once
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:, (*10)
\ParagonIE\Cookie\Cookie::setcookie('SID', '31d4d96e407aad42');
// or
\ParagonIE\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., (*11)
$cookie = new \ParagonIE\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;
$cookie->save();
The method calls can also be chained:, (*12)
(new \ParagonIE\Cookie\Cookie('SID'))->setValue('31d4d96e407aad42')->setMaxAge(60 * 60 * 24)->setSameSiteRestriction('Strict')->save();
A cookie can later be deleted simply like this:, (*13)
$cookie->delete();
Note: For the deletion to work, the cookie must have the same settings as the cookie that was originally saved. So you should remember to pass appropriate values to setPath(...), setDomain(...), setHttpOnly(...) and setSecureOnly(...) again., (*14)
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:, (*15)
// start session and have session cookie with 'lax' same-site restriction
\ParagonIE\Cookie\Session::start();
// or
\ParagonIE\Cookie\Session::start('Lax');
// start session and have session cookie with 'strict' same-site restriction
\ParagonIE\Cookie\Session::start('Strict');
// start session and have session cookie without any same-site restriction
\ParagonIE\Cookie\Session::start(null);
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., (*16)
Likewise, replacements for, (*17)
session_regenerate_id();
// and
session_regenerate_id(true);
are available via, (*18)
\ParagonIE\Cookie\Session::regenerate();
// and
\ParagonIE\Cookie\Session::regenerate(true);
if you want protection against session fixation attacks that comes with improved cookie handling., (*19)
Additionally, access to the current internal session ID is provided via, (*20)
\ParagonIE\Cookie\Session::id();
as a replacement for, (*21)
session_id();
Reading and writing session data
-
Read a value from the session (with optional default value):, (*22)
$value = \ParagonIE\Cookie\Session::get($key);
// or
$value = \ParagonIE\Cookie\Session::get($key, $defaultValue);
-
Write a value to the session:, (*23)
\ParagonIE\Cookie\Session::set($key, $value);
-
Check whether a value exists in the session:, (*24)
if (\ParagonIE\Cookie\Session::has($key)) {
// ...
}
-
Remove a value from the session:, (*25)
\ParagonIE\Cookie\Session::delete($key);
-
Read and then immediately remove a value from the session:, (*26)
$value = \ParagonIE\Cookie\Session::take($key);
$value = \ParagonIE\Cookie\Session::take($key, $defaultValue);
This is often useful for flash messages, e.g. in combination with the has(...) method., (*27)
Parsing cookies
$cookieHeader = 'Set-Cookie: test=php.net; expires=Thu, 09-Jun-2016 16:30:32 GMT; Max-Age=3600; path=/~rasmus/; secure';
$cookieInstance = \ParagonIE\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., (*28)
License
This project is licensed under the terms of the MIT License., (*29)
Wallogit.com
