README

AMPHP is a collection of event-driven libraries for PHP designed with fibers and concurrency in mind. This package provides an HTTP server plugin that simplifies session management for your applications. Effortlessly handle user sessions, securely managing data across requests.

Installation

This package can be installed as a Composer dependency.

composer require amphp/http-server-session

Usage

Basic usage

To read data from the session is straightforward:

$session->get('key'); // will read data stored in key 'key'

Note that get() will return null if the data in key are not found.

In order to write data, the session must be lock()ed first so that it cannot be written from anywhere else.

$session->lock();
$session->set('key', $data);
$session->commit(); // commits & unlocks

Calling commit() will store the data in the session storage and unlock the session.

Other important methods of the Session class are:

// regenerate the client id
$session->regenerate();

// force read from storage
$session->read();

// rollback what is `set()` in the session but has not been commit()ed yet
$session->rollback();

// destroy the session
$session->destroy();

Use the middleware to access Session in a RequestHandler

As this package is a plugin for amphp/http-server there is a middleware implementation available that injects the Session instance into the attributes of the Request. When the middleware is used the session is accessible from the attributes:

use Amp\Http\Server\Request;
use Amp\Http\Server\RequestHandler;
use Amp\Http\Server\Response;
use Amp\Http\Server\Session\Session;

class SomeRequestHandler implements RequestHandler
{
    public function handleRequest(Request $request): Response
    {
        /** @var Session $session */
        $session = $request->getAttribute(Session::class);

        // any operations on the session

        // return the response
    }
}

Note that if the attribute Session::class is not registered then getAttribute will throw a MissingAttributeError.

The middleware will handle setting and reading a session cookie in the request/response as well as releasing all locks on the session after the request has been processed.

If you haven't used middleware in amphp/http-server, follow the instructions on how to use middle ware with amphp/http-server.

A simple example is provided here examples/simple.php.

The SessionMiddleware can be further configured from the constructor regarding four different aspects:

• SessionFactory
• CookieAttributes
• Cookie name (default: 'session')
• Request attribute (default: Session::class)

The CookieAttributes is used to configure different cookie properties such as the expiry or the domain:

$cookieAttributes = CookieAttributes::default()
    ->withDomain('amphp.org')
    ->withExpiry(new \DateTime('+30 min'))
    ->withSecure();

Using the factory to create an instance of Session

Internally the session works with 3 dependencies:

• KeyedMutex - A synchronisation primitive to be used across contexts
• SessionStorage - Interface for reading and writing data.
• SessionIdGenerator - Interface for generating and validating a session ID.

An instance of the Session can be constructed easily using the provided SessionFactory

/** @var \Amp\Http\Server\Session\SessionFactory $factory */
$session = $factory->create($clientId);

This library comes with two storage implementations

• LocalSessionStorage - Default
• RedisSessionStorage - Storage in Redis

and one session ID generator

• Base64UrlSessionIdGenerator

The constructor of the SessionFactory allows to configure the factory with other implementations, so that subsequent calls to create() will use the new injected implementations. This can be beneficial in the certain scenarios, including testing.

Contributing

Please read our rules for details on our code of conduct, and the process for submitting pull requests to us.

Security

If you discover any security related issues, please use the private security issue reporter instead of using the public issue tracker.

License

The MIT License (MIT). Please see LICENSE for more information.