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
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.
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
NativeSession, has a
resume method which calls both
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);