A session library for PHP.

2.0.0 2016-10-11 05:16 UTC

This package is not auto-updated.

Last update: 2024-05-25 17:01:26 UTC


Build Status Code Quality Code Climate PHP 7 ready HHVM Latest Stable Version License

phossa2/session is a session library for PHP.

It requires PHP 5.4, supports PHP 7.0+ and HHVM. It is compliant with PSR-1, PSR-2, PSR-3, PSR-4, and the proposed PSR-5.



Install via the composer utility.

composer require "phossa2/session"

or add the following lines to your composer.json

    "require": {
       "phossa2/session": "2.*"


Start the session, normally in your bootstrap file.

use Phossa2\Session\Session;
use Phossa2\Session\Carton;

// start a 'global' session
$sessGlobal = new Session('global');

// set 'global' session as the default

// start another 'private' session at the same time
$sessPrivate = new Session('private');

Then in your code using session data,

// a box using default session 'global'
$boxGlobal = new Carton();

// global counter

// another box named 'toy' using the private session
$boxPrivate = new Carton('toy', $sessPrivate);

// private counter


  • Multiple sessions supported

    Phossa2\Session\Session uses its own infra-structure. It can co-exists with other session libs or PHP session. By default, it uses cookie as session id exchange protocol. Different session then use different cookies.

    // use a cookie named 'one'
    $sessOne = new Session('one');
    // use a cookie named 'two'
    $sessTwo = new Session('two');

    Close or destroy one session has no influence on other sessions.

  • Data seperation using Carton

    In PHP session, session data is stored in the global variable $_SESSION. It provides storage only and there are no other utilities.

    Phossa2\Session\Carton is a sandbox for data. User may name a carton box instead of using the default name 'default'. Or even attach to a different session instead of using the default session.

    // box 1
    $boxOne = new Carton('one', $sessPrivate);
    $boxOne['drone'] = 2;
    // box 2
    $boxTwo = new Carton('two', $sessPrivate);
    $boxTwo['drone'] = 1;

    If either $name or $session is different, then the data is in different namespaces.

    By extending Phossa2\Session\Carton, user may even provide utilities, such as data locking, usage monitoring, access control etc.

  • Extending the library

    phossa2/session refactors most of its dependents into seperate classes.

    • Session saving handler

      Handler is implementing the most widely adopted \SessionHandlerInterface shipped in PHP. If no handler injected into session, it will utilize the Phossa2\Session\Handler\FileHandler by default.

      use Phossa2\Session\Handler\StorageHandler;
      // inject a phossa2/storage handler
      $session->setHandler(new StorageHandler($storage, '/tmp/session'));
    • Session id exchange protocol

      Driver is implementing Phossa2\Session\Interfaces\DriverInterface. By default, the Phossa2\Session\Driver\CookieDriver is used to set/get/del session id on the client side by using cookies.

      Users may write their own drivers to communicate with the client.

      use My\Own\HeaderDriver;
      // stores session id in `X-My-Own-Session` header
      $session->setDriver(new HeaderDriver());
    • Session validation

      Multiple validators may be injected into session to do validation.

      use Phossa2\Session\Validator\RemoteIp;
      $session->addValidator(new RemoteIp());
    • Session id generator

      By default, session id is generated by a built-in routine. User may use his own generator such as using phossa2/uuid.

      use Phossa2\Session\Generator\UuidGenerator;
      $session->setGenerator(new UuidGenerator());
    • Middleware support

      Middleware of this lib can be found in phossa2/middleware

Change log

Please see CHANGELOG from more information.


$ composer test


Please see CONTRIBUTE for more information.


  • PHP >= 5.4.0

  • phossa2/shared >= 2.0.21


MIT License