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

phossa2 / session

Maintainers

Details