altmetric / mongo-session-handler

A PHP session handler backed by MongoDB

THIS PROJECT IS DEPRECATED

mongo-session-handler is not maintained anymore.

Mongo Session Handler

A PHP session handler backed by MongoDB.

Current version: 2.1.0
Supported PHP versions: 5.4, 5.5, 5.6, 7

Note: This package depends on the MongoDB PHP driver extension (mongodb) and its companion PHP library. If you need to use the older, legacy driver (mongo), please see version 1.0.

Installation

$ composer require altmetric/mongo-session-handler:^2.1

Usage

<?php
use Altmetric\MongoSessionHandler;

$sessions = $mongoClient->someDB->sessions;
$handler = new MongoSessionHandler($sessions);

session_set_save_handler($handler);
session_set_cookie_params(0, '/', '.example.com', false, true);
session_name('my_session_name');
session_start();

API Documentation

public MongoSessionHandler::__construct(MongoDB\Collection $collection[, Psr\Log\LoggerInterface $logger])

$handler = new \Altmetric\MongoSessionHandler($client->db->sessions);
session_set_save_handler($handler);
session_start();

$handler = new \Altmetric\MongoSessionHandler($client->db->sessions, $logger);

Instantiate a new MongoDB session handler with the following arguments:

• $collection: a MongoDB\Collection collection to use for session storage;
• $logger: an optional PSR-3-compliant logger.

The given $collection will be populated with documents using the following schema:

• _id: the String session ID;
• data: the session data stored as a MongoDB\BSON\Binary object using the old generic binary format for compatibility with older versions of this library;
• last_accessed: a MongoDB\BSON\UTCDateTime representation of the time this session was last written to.

This handler implements the SessionHandlerInterface meaning that it can be registered as a session handler with session_set_save_handler.

Expiring sessions

If you wish to clean up expired sessions using SessionHandlerInterface::gc, ensure that your session.gc_divisor, session.gc_probability and session.gc_maxlifetime settings are populated accordingly, e.g. the following settings in your php.ini mean that sessions that haven't been updated in over an hour have a 1% chance of being cleaned whenever someone starts a new session:

session.gc_probability = 1
session.gc_divisor = 100
session.gc_maxlifetime = 3600

In order to keep session cleaning fast, you should add an index on the last_accessed field of your session $collection, e.g.

db.sessions.createIndex({last_accessed: 1});

Concurrency

As MongoDB prior to 3.0 does not support document level locking, this session handler operates on a principle of Last Write Wins.

If a user of a session causes two simultaneous writes then you may end up with the following situation:

1. Window A reads session value of ['foo' => 'bar'];
2. Window B reads session value of ['foo' => 'bar'];
3. Window B writes session value of ['foo' => 'baz'];
4. Window A writes session value of ['foo' => 'quux'].

The session will now contain ['foo' => 'quux'] as it was the last successful write. This may be surprising if you're trying to increment some value in a session as it is not locked during reads and writes:

1. Window A reads session value of ['count' => 0];
2. Window B reads session value of ['count' => 0];
3. Window B writes session value of ['count' => 1];
4. Window A writes session value of ['count' => 1].

Acknowledgements

• Nick Ilyin's php-mongo-session served as a valuable existing implementation of MongoDB-backed sessions in PHP.
• Thanks to Josh Ribakoff for suggesting that the logger should be optional.

License

Copyright © 2015-2017 Altmetric LLP

Distributed under the MIT License.

mongo-session-handler's Issues

No gc on ubuntu

Ubuntu disables gc in favor of a custom cron to cleanup old sessions (the rationale is something with user permissions I think), so this class' gc method will never be called on ubuntu & sessions will keep growing.

Perhaps providing a CLI tool to cleanup sessions that Ubuntu users can add to their cron, or just a warning in the readme might suffice. Most people would be using Debian instead of Ubuntu, but lots use Ubuntu for development.