README

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.

Highlights

• Able to co-exists with other session libs or utilities including PHP session.

• Able to run multiple sessions at the same time.

• Data seperation using cartons.

• Handler, driver, validator support and dependency injection.

• Middleware support.

Installation

Install via the composer utility.

composer require "phossa2/session"

or add the following lines to your composer.json

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

Usage

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
Carton::setDefaultSession($sessGlobal);

// 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
++$boxGlobal['counter'];

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

// private counter
++$boxPrivate['counter'];

Features

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

Testing

$ composer test

Contributing

Please see CONTRIBUTE for more information.

Dependencies

• PHP >= 5.4.0

• phossa2/shared >= 2.0.21

License

MIT License