amphp / aerys-session
An HTTP server plugin that simplifies session management for your applications. Effortlessly handle user sessions, securely managing data across requests.
Fund package maintenance!
amphp
Requires
- php: >=8.1
- amphp/amp: ^3
- amphp/cache: ^2
- amphp/http: ^2
- amphp/http-server: ^3
- amphp/serialization: ^1
- amphp/sync: ^2
- paragonie/constant_time_encoding: ^2.2
Requires (Dev)
- amphp/php-cs-fixer-config: ^2
- amphp/phpunit-util: ^3
- amphp/redis: ^2
- league/uri: ^6
- phpunit/phpunit: ^9
- psalm/phar: ^5
Suggests
- amphp/redis: Allows storing session data in Redis
Conflicts
- amphp/redis: <2 || >=3
This package is auto-updated.
Last update: 2023-12-03 19:13:39 UTC
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 contextsSessionStorage
- 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.