README

UserlandSession is an HTTP cookie-based session components implemented in plain PHP, allowing it to be used concurrently with--and completely independent of--existing native sessions. This makes it handy for bridging session state across multiple PHP apps with incompatible sessions.

Loosely-coupled components that introduce no global state (except headers)
Uses PHP's SessionHandlerInterface, so you can re-use existing 3rd-party handlers
Session data is only accessible via the object instead of a global

// create a files-based session, directory sniffed from session.save_path
$session = \UserlandSession\SessionBuilder::instance()->build();
$session->start();

// use public $session->data array property...
$session->data['foo'] = 'bar';

// ...or use set/get()
$session->set('foo', 'bar');

$session->writeClose(); // ...or let destructor do this

Handlers

The save handler interface is PHP's SessionHandlerInterface, and handlers FileHandler and PdoHandler are included.

Feel free to use your own save handler class, or use these as handlers for native sessions!

Creating a Session

Easy ways to get a files-based session:

// from script (save path sniffed from session.save_path)
$session = (require 'path/to/UserlandSession/scripts/get_file_session.php');

// using builder (here we set the session name to MYSESS)
$session = SessionBuilder::instance()
    ->setSavePath('/tmp')
    ->setName('MYSESS')
    ->build();

File Storage Options

// turn off file locking
$session = SessionBuilder::instance()
    ->setFileLocking(false)
    ->build();

Using PDO

// pre-existing PDO connection
$session = SessionBuilder::instance()
    ->setPdo($myConnection)
    ->setTable('userland_sessions')
    ->build();

// or if you want it to connect for you when needed:
$session = SessionBuilder::instance()
    ->setDbCredentials(array(
        'dsn' => 'mysql:host=localhost;dbname=ulsess;charset=UTF8',
        'username' => 'fred',
        'password' => 'password1',
    ))
    ->setTable('userland_sessions')
    ->build();

Extras

You can check for data matching the client's cookie without starting the session:

if ($session->sessionLikelyExists()) {
    $session->start();
    // use session
} else {
    // don't start if we don't need to
}

Simpler cookie removal:

$session->removeCookie();

// or specify true when destroying the session
$session->destroy(true);

License

MIT. See LICENSE.

mrclay / userland-session

Maintainers

Details