Session Abstraction

PHP already has robust capabilities for handling client sessions. With the release of PHP 5.4, the release of the SessionHandlerInterface saw the chance for developers to craft their own session handlers. Suddenly, anything was possible and you didn't have to depend on an extension for alternate session storage.

Yet, the built-in session management in PHP is rather simple. As-is, developers don't have a means to watch for session-related events. Also rather simple is the storage of session variables. Developers can use the super-global $_SESSION array to store key-value pairs, but there was no way to guarantee that libraries writing to the session values didn't clobber values the developer was storing.

This is where caridea-session comes in.

The Session Interface

The Session interface is the real face of the caridea-session library. It allows you the ability to not only manage session state (like the PHP session functions already do), but it also handles the aforementioned problems: event publishing and value namespacing.


The isStarted method returns whether a session is currently active. The canResume method returns whether a session had previously been active, and could be resumed. The default implementation of the Session interface, NativeSession, has a resume method which calls both isStarted and canResume. The following code will reliably start or resume a session.

$session->resume() || $session->start();

In the default implementation, the resume method calls start under the hood, but only if the session has been started before (that is, if the user supplies a session cookie).


Once a session is started, you can call the destroy method to end it. You can also call regenerateId if you need to do that.


You can call the getValues method with a namespace argument to get a Map of values. See the values documentation for more information. You can also call the clear method to remove all currently set values.


This class uses PHP's native session functions under the hood. To create a new one, you need at least one argument: the cookies array.

$session = new \Caridea\Session\NativeSession($_COOKIE);

The second (optional) argument is a list of any session plugins you wish to register. See the plugins documentation for more information.

$plugins = [new \Caridea\Session\CsrfPlugin()];
$session = new \Caridea\Session\NativeSession($_COOKIE, $plugins);