Comodojo/cookies documentation¶
Minimalist and extensible library to manage cookies.
Introduction¶
This library aims to provide an OO approach to defining cookies and to simplify cookies’ management.
It includes also a cookie manager class that can handle multiple cookies at the same time.
Installation¶
First install composer, then:
composer require comodojo/cookies
Requirements¶
To work properly, comodojo/cookies requires PHP >=5.4.0.
General Usage¶
Creating a new cookie¶
A cookie can be defined creating a new instance of Comodojo\Cookies\Cookie, or one of the other Cookie types.
Once defined, additional methods can be used to set/get cookie properties, but cookie is just a server-side object.
Nothing is passed to the client until the Cookie::save() method is invoked.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 | <?php
use \Comodojo\Cookies\Cookie;
// create a new cookie instance
$cookie = new Cookie('my-cookie');
// set cookie's properties
$cookie->setValue( "Lorem ipsum dolor" )
->setExpire( time()+3600 )
->setPath( "/myapp" )
->setDomain( "example.com" )
->setSecure()
->setHttponly();
// persist the cookie
$result = $cookie->save();
|
Alternatively, the static constructor Cookie::create is available to quikly create a cookie.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 | <?php
use \Comodojo\Cookies\Cookie;
// define a new cookie
$cookie = Cookie::create('my_cookie', array(
'value' => "Lorem ipsum dolor"
'expire' => time()+3600
'path' => "/myapp"
'domain' => "example.com"
'secure' => true
'httponly' => true
)
);
// persist the cookie
$result = $cookie->save();
|
Loading a cookie¶
An existent cookie can be easily loaded using the Cookie::load() method.
1 2 3 4 5 6 7 8 9 10 11 12 | <?php
use \Comodojo\Cookies\Cookie;
// create a new cookie instance
$cookie = new Cookie('my-cookie');
// load cookie
$cookie->load();
// read the cookie value
$value = $cookie->getValue();
|
The static constructor Cookie::retrieve can be used to speed up operation.
1 2 3 4 5 6 7 8 9 | <?php
use \Comodojo\Cookies\Cookie;
// create a new cookie instance
$cookie = Cookie::retrieve('my-cookie');
// read the cookie value
$value = $cookie->getValue();
|
Cookie size¶
By default maximum allowed lenght for a cookie is 4000 bytes, to allow it to work in all major browsers.
Note
General informations about cookie limits is available in the rfc6265. See also this site for more informations.
Maximum cookie size can be overridden when creating a cookie.
1 2 3 4 5 6 | <?php
use \Comodojo\Cookies\Cookie;
// create a new cookie instance with m-size of approximately 3k
$cookie = new Cookie('my-cookie', 3000);
|
Note
The real available size of cookie can <4KB due to serialization and (in case) encryption. In case of cookie > 4KB, a \Comodojo\Exception\CookieException is raised.
Content serialization¶
By default a cookie will serialize/unserialize it’s content prior to be setted/loaded.
This behaviour can be overridden in Cookie::setValue and Cookie::getValue methods.
1 2 3 4 5 6 7 8 9 | <?php
use \Comodojo\Cookies\Cookie;
// create a new cookie instance
$cookie = new Cookie('my-cookie');
// set a plain value (no serialization)
$cookie->setValue("Lorem ipsum dolor", false);
|
Cookie types¶
Plain cookie¶
Plain cookies are just an OO implementation of standard cookies. As an option, cookie content can be serialized on the client side.
1 2 3 4 5 6 | <?php
use \Comodojo\Cookies\Cookie;
// create a new cookie instance with m-size of approximately 3k
$cookie = new Cookie('my-cookie');
|
Encrypted cookie¶
The class \Comodojo\Cookies\EncryptedCookie provides an extension of plain cookie in which cookie content is encrypted using a 256bit AES key, that should be provided to class contructor.
To setup a EncryptedCookie:
1 2 3 4 5 6 | <?php
use \Comodojo\Cookies\EncryptedCookie;
// create a new cookie instance with m-size of approximately 3k
$cookie = new EncryptedCookie('my-cookie', 'my-super-secret-key');
|
Secure cookie¶
The class \Comodojo\Cookies\SecureCookie provides an extension of Encrypted Cookie to ensure a minimum protection from cookie spoofing.
The crypto key is calculated using both user defined secret and IP informations from $_SERVER superglobal (if available).
This can be useful in internal networks or where clients does not often change IP address.
To setup a SecureCookie:
1 2 3 4 5 6 | <?php
use \Comodojo\Cookies\SecureCookie;
// create a new cookie instance with m-size of approximately 3k
$cookie = new SecureCookie('my-cookie', 'my-super-secret-key');
|
Extending¶
A custom cookie can be easily created implementing the \Comodojo\Cookies\CookieInterface interface.
Additionally, the abstract class \Comodojo\Cookies\AbstractCookie can be used to reuse common cookie methods.
Cookie Manager¶
Cookie manager is a class that can handle multiple cookies at the same time.
Each managed cookie object must implement the \Comodojo\Cookies\CookieInterface.
Saving multiple cookies¶
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 | <?php
use \Comodojo\Cookies\Cookie;
use \Comodojo\Cookies\CookieManager;
// create two different cookies
$first_cookie = new Cookie('first_cookie');
$second_cookie = new Cookie('second_cookie');
// init the manager
$manager = new CookieManager();
// add cookies to the manager
$manager
->add($first_cookie)
->add($second_cookie);
// save them all
$result = $manager->save();
|
Loading multiple cookies¶
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 | <?php
use \Comodojo\Cookies\Cookie;
use \Comodojo\Cookies\CookieManager;
// create two different cookies
$first_cookie = new Cookie('first_cookie');
$second_cookie = new Cookie('second_cookie');
// init the manager
$manager = new CookieManager();
// add cookies to the manager
$manager
->add($first_cookie)
->add($second_cookie);
// load cookies and retrieve contents
$result = $manager->load()->getValues();
|