From 47b246a690254028fe33a19d8a81bcc1197a8394 Mon Sep 17 00:00:00 2001 From: AMPHP Bot Date: Sun, 3 Dec 2023 20:55:10 +0100 Subject: [PATCH] Sync http-server-session.md --- http-server-session.md | 150 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 150 insertions(+) create mode 100644 http-server-session.md diff --git a/http-server-session.md b/http-server-session.md new file mode 100644 index 0000000..e45e2c2 --- /dev/null +++ b/http-server-session.md @@ -0,0 +1,150 @@ +--- +notice: 'This file is imported and can be edited at https://github.com/amphp/http-server-session/blob/3.x/README.md' +title: 'Session Handling for HTTP servers in PHP' +description: 'Learn how to handle user sessions, securely managing data across requests.' +image: undraw/undraw_logistics.svg +permalink: /http-server-session +source: 'https://github.com/amphp/http-server-session/blob/3.x/README.md' +layout: docs +--- +AMPHP is a collection of event-driven libraries for PHP designed with fibers and concurrency in mind. This package provides an [HTTP server](https://amphp.org/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](https://getcomposer.org/) dependency. + +```bash +composer require amphp/http-server-session +``` + +## Usage + +#### Basic usage + +To read data from the session is straightforward: + +```php +$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. + +```php +$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: + +```php +// 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`](https://github.com/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: + +```php +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`](https://github.com/amphp/http-server#middleware). + +A simple example is provided here [`examples/simple.php`](https://github.com/amphp/http-server-session/blob/3.x/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: + +```php +$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`](https://github.com/amphp/sync/blob/2.x/src/KeyedMutex.php) - A synchronisation primitive to be used across contexts +* [`SessionStorage`](https://github.com/amphp/http-server-session/blob/3.x/src/SessionStorage.php) - Interface for reading and writing data. +* [`SessionIdGenerator`](https://github.com/amphp/http-server-session/blob/3.x/src/SessionIdGenerator.php) - Interface for generating and validating + a session ID. + +An instance of the [`Session`](https://github.com/amphp/http-server-session/blob/3.x/src/Session.php#L28) can be constructed easily using +the provided [`SessionFactory`](https://github.com/amphp/http-server-session/blob/3.x/src/SessionFactory.php) + +```php +/** @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](https://amphp.org/contributing) 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](./LICENSE) for more information.