PHPackages                             amphp/aerys-session - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [HTTP & Networking](/categories/http)
4. /
5. amphp/aerys-session

Abandoned → [amphp/http-server-session](/?search=amphp%2Fhttp-server-session)Library[HTTP & Networking](/categories/http)

amphp/aerys-session
===================

 An HTTP server plugin that simplifies session management for your applications. Effortlessly handle user sessions, securely managing data across requests.

v3.0.1(4mo ago)191958[1 PRs](https://github.com/amphp/http-server-session/pulls)MITPHPPHP >=8.1CI passing

Since Feb 24Pushed 4mo ago8 watchersCompare

[ Source](https://github.com/amphp/http-server-session)[ Packagist](https://packagist.org/packages/amphp/aerys-session)[ Docs](https://amphp.org/http-server-session)[ GitHub Sponsors](https://github.com/amphp)[ RSS](/packages/amphp-aerys-session/feed)WikiDiscussions 3.x Synced 1mo ago

READMEChangelog (10)Dependencies (13)Versions (25)Used By (0)

http-server-session
===================

[](#http-server-session)

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
------------

[](#installation)

This package can be installed as a [Composer](https://getcomposer.org/) dependency.

```
composer require amphp/http-server-session
```

Usage
-----

[](#usage)

#### Basic 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

[](#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:

```
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:

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

#### Using the factory to create an instance of Session

[](#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)

```
/** @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
------------

[](#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
--------

[](#security)

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

License
-------

[](#license)

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

###  Health Score

54

—

FairBetter than 97% of packages

Maintenance77

Regular maintenance activity

Popularity22

Limited adoption so far

Community22

Small or concentrated contributor base

Maturity82

Battle-tested with a long release history

 Bus Factor1

Top contributor holds 50% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~150 days

Recently: every ~256 days

Total

25

Last Release

124d ago

Major Versions

0.3.x-dev → v1.0.02018-12-12

v1.0.1 → v2.0.0-rc12019-09-12

v2.0.0 → v3.0.0-beta.12022-05-16

v2.0.1 → v3.0.0-beta.22023-04-22

PHP version history (4 changes)v0.1.0PHP ^7

v1.0.0PHP >=7.1.0

v1.0.1PHP >=7.1

v3.0.0-beta.1PHP >=8.1

### Community

Maintainers

![](https://www.gravatar.com/avatar/12852217f3369e8144bc9ce6ac2a2341c28c5512c5b3df5749bfbbd45b6877ff?d=identicon)[kelunik](/maintainers/kelunik)

![](https://www.gravatar.com/avatar/f6db63ad594446f67d79532b75c69439fd0df779cc90868b43c187c02a4221ef?d=identicon)[bwoebi](/maintainers/bwoebi)

---

Top Contributors

[![kelunik](https://avatars.githubusercontent.com/u/2743004?v=4)](https://github.com/kelunik "kelunik (90 commits)")[![trowski](https://avatars.githubusercontent.com/u/1628287?v=4)](https://github.com/trowski "trowski (50 commits)")[![bwoebi](https://avatars.githubusercontent.com/u/3154871?v=4)](https://github.com/bwoebi "bwoebi (32 commits)")[![cspray](https://avatars.githubusercontent.com/u/771345?v=4)](https://github.com/cspray "cspray (3 commits)")[![assertchris](https://avatars.githubusercontent.com/u/200609?v=4)](https://github.com/assertchris "assertchris (2 commits)")[![wtsergo](https://avatars.githubusercontent.com/u/305326?v=4)](https://github.com/wtsergo "wtsergo (1 commits)")[![staabm](https://avatars.githubusercontent.com/u/120441?v=4)](https://github.com/staabm "staabm (1 commits)")[![thgs](https://avatars.githubusercontent.com/u/8940963?v=4)](https://github.com/thgs "thgs (1 commits)")

---

Tags

amphpphprevoltsession

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/amphp-aerys-session/health.svg)

```
[![Health](https://phpackages.com/badges/amphp-aerys-session/health.svg)](https://phpackages.com/packages/amphp-aerys-session)
```

###  Alternatives

[amphp/http-server

A non-blocking HTTP application server for PHP based on Amp.

1.3k4.5M81](/packages/amphp-http-server)[danog/madelineproto

Async PHP client API for the telegram MTProto protocol.

3.4k855.0k18](/packages/danog-madelineproto)[amphp/http-client

An advanced async HTTP client library for PHP, enabling efficient, non-blocking, and concurrent requests and responses.

7286.8M137](/packages/amphp-http-client)[amphp/redis

Efficient asynchronous communication with Redis servers, enabling scalable and responsive data storage and retrieval.

165634.7k44](/packages/amphp-redis)[amphp/parallel

Parallel processing component for Amp.

84746.2M74](/packages/amphp-parallel)[amphp/websocket-client

Async WebSocket client for PHP based on Amp.

1613.0M39](/packages/amphp-websocket-client)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)