ujjwal/psr7-http-session

Alternative to PHP's native session handler for PSR-7

PSR-7 Session

![Coverage Status][coverage-image] , _(*1)

Alternative to PHP's native session handler. It does not depend on PHP's session capability. It can be used with non-typical php based applications like with react/http., _(*2)

But, why?

- You don't have to depend on session_ functions which means you can write testable code. - You don't have to depend on $_SESSION superglobal allowing you to write more testable code. - You can even use this for non-typical php based applications like with react/http. - You can create a framework agnostic library/module depending on psr-7 HTTP message interfaces and this session library., _(*3)

Getting started

$sessionOptions = [
    'name' => 'session_id',
    'sid_length' => 40,
    'cookie' => [
        'domain' => 'your-app.com',
    ]
];

$sessionHandler = new Ojhaujjwal\Session\Handler\FileHandler('path/to/session-data');
$sessionManager = new Ojhaujjwal\Session\SessionManager(
    $sessionHandler,
    $request,
    $sessionOptions
);
$storage = $sessionManager->getStorage();

$sessionManager->start();

// you can manipulate $storage just like $_SESSION   
$storage['some_key'] = 'some_value';
$someKey = $storage['some_key'];

$response = $sessionManager->close($response);
//return the response the the client

Installation

composer require ujjwal/psr7-http-session, _(*4)

Session Options

name

Type: string Required: true, _(*5)

Name of the session which is used as cookie name. It should only contain alphanumeric characters., _(*6)

sid_length

Type: integer Default: 40, _(*7)

the length of session ID string. Session ID length can be between 22 to 256., _(*8)

cookie

Type: array, _(*9)

Used to pass cookie options. See cookie options section., _(*10)

Cookie Options

domain

Type: string Default: derived from the Host header of request, _(*11)

domain to be set in the session cookie., _(*12)

path

Type: string Default: /, _(*13)

path to be set in the session cookie., _(*14)

http_only

Type: boolean Default: true, _(*15)

Marks the cookie as accessible only through the HTTP protocol. This means that the cookie won't be accessible by scripting languages, such as JavaScript., _(*16)

secure_only

Type: boolean Default: True if the original request is https, _(*17)

It indicates whether cookies should only be sent over secure connections., _(*18)

lifetime

Type: integer Default: 0 for session cookie, _(*19)

It specifies the lifetime of the cookie in seconds which is sent to the browser. The value 0 means "until the browser is closed." Defaults to 0, _(*20)

same_site

Type: string Default: Lax Specifies SameSite cookie attribute. Very useful to mitigate CSRF by preventing the browser from sending this cookie along with cross-site requests. Allowed values: * empty string for not setting the attribute * ParagonIE\Cookie\Cookie::SAME_SITE_RESTRICTION_LAX(fairly strict) * ParagonIE\Cookie\Cookie::SAME_SITE_RESTRICTION_STRICT(very strict), _(*21)

Basic operations

Initializing SessionManager

$sessionManager = new Ojhaujjwal\Session\SessionManager(
    $sessionHandler,
    $request,
    $sessionOptions
);

Starting session

$sessionManager->start();

$sessionManager->isStarted(); // returns true

Retrieve session id

$sessionManager->getId(); //returns alphanumeric string

Regenerate session id

$sessionManager->regenerate();

$sessionManager->regenerate(false); // does not destroy old session

Close session and write to response header as cookie

$response = $sessionManager->close($response);

Retrieving session storage

$storage = $sessionManager->getStorage();

It implements IteratorAggregate, ArrayAccess, Countable So, it will look very much like $_SESSION. Just replace the $_SESSION occurrences in your app with instance of the object., _(*22)

Write to session

$storage->abcd = 'efgh';
//or
$storage['abcd'] = 'efgh';
//or
$storage->set('abcd', 'efgh');

Read from session

$abcd =  $storage->abc;
//or
$abcd = $storage['abcd'];
//or
$abcd = $storage->get('abcd');

Remove from session

unset($storage->abc);
//or
unset($storage['abcd']);
//or
$storage->remove('abcd');

Flush session data

$storage->flush();

Session Middleware

It also comes with a http middleware which you can use to automatically initialize session and write cookie to response. The middleware is compatible with http-interop/http-middleware based single pass approach or express-like double pass approach., _(*23)

 $middleware = new Ojhaujjwal\Session\SessionMiddleware($handler, $sessionOptions);
 $middleware->process($request, $delegate);
 // or
 $middleware($request, $response, $next);

 //using with zend-expressive
 //after errorhandler and before the routing middleware
 $app->pipe(\Ojhaujjwal\Session\SessionMiddleware::class);

TODO

• [ ] Fix build in php7.2
• [ ] Garbage collection
• [ ] Cookie Based session handler
• [ ] Encryption Session Handler

License

MIT, _(*24)