Skip to content

README.md

Latest commit

 

History

History
125 lines (77 loc) · 5.71 KB

README.md

File metadata and controls

125 lines (77 loc) · 5.71 KB

PHP Sessionz CI Latest Stable Version License

Sessionz is a PHP library for smarter session management in modular applications.

Requirements

  • PHP 7.4 or newer (tested against 7.4, 8.0, 8.1, 8.2, 8.3, 8.4, and 8.5)
  • Composer

Installation

composer require ericmann/sessionz

Quick Start

After loading your autoloader, initialize the core session manager and register the handlers you need:

require __DIR__ . '/vendor/autoload.php';

EAMann\Sessionz\Manager::initialize()
    ->addHandler( new \EAMann\Sessionz\Handlers\DefaultHandler() )
    ->addHandler( new \EAMann\Sessionz\Handlers\EncryptionHandler( getenv('session_passkey') ) )
    ->addHandler( new \EAMann\Sessionz\Handlers\MemoryHandler() );

session_start();

The above example adds, in order:

  • The default PHP session handler (which uses files for storage)
  • An encryption middleware such that session data will be encrypted at rest on disk
  • An in-memory cache to avoid round-trips to the filesystem on read

How Handlers Work

The session manager maintains a list of registered "handlers" to which it passes requests from the PHP engine to:

  • Read a session
  • Write a session
  • Create a session store
  • Clean up (garbage collect) expired sessions
  • Delete a session

Each handler must implement the Handler interface so the session manager knows how to work with them.

Middleware Structure

The overall structure of the handler stack is identical to that of a middleware stack in a modern PHP application. You can read more about the general philosophy on Slim's website.

In general, stack operations will flow from the outside-in, starting by invoking the appropriate operation on the most recently registered handler and walking down the stack to the oldest handler. Each handler has the option to halt execution and return data immediately, or can invoke the passed $next callback to continue operation.

Using the quick start example above:

  • Requests start in the MemoryHandler
  • If necessary, they then pass to the EncryptionHandler
  • Requests always pass from encryption to the DefaultHandler
  • If necessary, they then pass to the (hidden) BaseHandler
  • Then everything returns because the base handler doesn't pass anything on

Available Handlers

DefaultHandler

The default session handler merely exposes PHP's default session implementation to our custom manager. Including this handler will provide otherwise standard PHP session functionality to the project as a whole, but this functionality can be extended by placing other stacks on top.

EncryptionHandler

Sessions stored on disk (the default implementation) or in a separate storage system (Memcache, MySQL, or similar) should be encrypted at rest. This handler will automatically encrypt any information passing through it on write and decrypt data on read. It does not store data on its own.

This handler requires a symmetric encryption key when it's instantiated. This key should be an ASCII-safe string generated by Defuse PHP Encryption (a dependency of this library):

use Defuse\Crypto\Key;

$rawKey = Key::createNewRandomKey();
$key    = $rawKey->saveToAsciiSafeString();

// Store $key somewhere safe (e.g. an environment variable) and pass it
// back into the EncryptionHandler constructor on every request.

MemoryHandler

If the final storage system presented to the session manager is remote, reads and writes can take a non-trivial amount of time. Storing session data in memory helps to make the application more performant. Reads will stop at this layer in the stack if the session is found (i.e. the cache is hot) but will flow to the next layer if no session exists. When a session is found in a subsequent layer, this handler will update its cache to make the data available upon the next lookup.

Writes will update the cache and pass through to the next layer in the stack.

Abstract handlers

The BaseHandler class is always instantiated and included at the root of the handler stack by default. This is so that, no matter what handlers you add in to the stack, the session manager will always return a standard, reliable set of information.

The NoopHandler class is provided for you to build additional middleware atop a standard interface that "passes through" to the next layer in the stack by default. The EncryptionHandler, for example, inherits from this class as it doesn't store or read data, but merely manipulates information before passing it along. Another implementation might be a logging interface to track when sessions are accessed/updated.

Development

Clone the repository and install dev dependencies:

git clone https://github.com/ericmann/sessionz.git
cd sessionz
composer install

Run the test suite:

composer test

Static analysis is provided by PHPStan and runs automatically in CI.

Contributing

Issues and pull requests are welcome at https://github.com/ericmann/sessionz. Please ensure new code is covered by tests and that composer test passes across the supported PHP matrix before opening a PR.

License

MIT

Credits

The middleware implementation is inspired heavily by the request middleware stack presented by the Slim Framework.