PHPackages                             juliangut/sessionware - 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. juliangut/sessionware

ActiveLibrary

juliangut/sessionware
=====================

PSR7 session management middleware

1.2.1(9y ago)278BSD-3-ClausePHP >=5.5

Since Apr 23Compare

[ Source](https://github.com/juliangut/sessionware)[ Packagist](https://packagist.org/packages/juliangut/sessionware)[ Docs](https://github.com/juliangut/sessionware)[ RSS](/packages/juliangut-sessionware/feed)WikiDiscussions Synced 2mo ago

READMEChangelogDependencies (10)Versions (8)Used By (0)

[![PHP version](https://camo.githubusercontent.com/8c508dbfb530cc5703d088796f65f3230e83d32a68e84c73bc9e7847b12a0fa7/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d253345253344352e352d3838393242462e7376673f7374796c653d666c61742d737175617265)](http://php.net)[![Latest Version](https://camo.githubusercontent.com/09c06a349416ee9c0132cba9b27faee935593491aec6705d80806ff96c0d8352/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f767072652f6a756c69616e6775742f73657373696f6e776172652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/juliangut/sessionware)[![License](https://camo.githubusercontent.com/a442d0f637b1dc60e521003b843fbd47dcb35dc876aa370049e630ba7a4ec32b/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f6a756c69616e6775742f73657373696f6e776172652e7376673f7374796c653d666c61742d737175617265)](https://github.com//sessionware/blob/master/LICENSE)

[![Build status](https://camo.githubusercontent.com/c3f4e6e84b651c5e923452b4e2ddd1281e39df6da5ab91251513eb613694e7b7/68747470733a2f2f696d672e736869656c64732e696f2f7472617669732f6a756c69616e6775742f73657373696f6e776172652e7376673f7374796c653d666c61742d737175617265)](https://travis-ci.org/juliangut/sessionware)[![Style](https://camo.githubusercontent.com/98390a29062c5694a38e5e7c305a4232cebc72ae7494d51e95aad998ee5fcb2a/68747470733a2f2f7374796c6563692e696f2f7265706f732f35363333363032322f736869656c64)](https://styleci.io/repos/56336022)[![Code Quality](https://camo.githubusercontent.com/de9ed9f2d29a4f596c4268bc55cd6ed4c4d14290a06aae37d02bb9198e4735db/68747470733a2f2f696d672e736869656c64732e696f2f7363727574696e697a65722f672f6a756c69616e6775742f73657373696f6e776172652e7376673f7374796c653d666c61742d737175617265)](https://scrutinizer-ci.com/g/juliangut/sessionware)[![Code Coverage](https://camo.githubusercontent.com/75b68abb7259c24d871541624eb9f68c5fcfdff8f24c4c145b128a6284d247a0/68747470733a2f2f696d672e736869656c64732e696f2f636f766572616c6c732f6a756c69616e6775742f73657373696f6e776172652e7376673f7374796c653d666c61742d737175617265)](https://coveralls.io/github/juliangut/sessionware)[![Total Downloads](https://camo.githubusercontent.com/a05de0aa8154dbffb58634d5eaa0a4fb1c45eb8a35aeb6919efb1ef9413423c8/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6a756c69616e6775742f73657373696f6e776172652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/juliangut/sessionware)

SessionWare
===========

[](#sessionware)

A PSR7 session management middleware.

Automatic control of session timeout.

Generates a 80 character long session\_id using `random_bytes`, a truly cryptographically secure pseudo-random generator, instead of `session.hash_function` hash algorithm.

#### Important considerations

[](#important-considerations)

Be aware that this middleware needs some session `ini` settings to be set to specific values:

`session.use_trans_sid` to `false``session.use_cookies` to `true``session.use_only_cookies` to `true``session.use_strict_mode` to `false``session.cache_limiter` to '' (empty string)

This values will prevent session headers to be automatically sent to user. **It's the developer's responsibility to include corresponding cache headers in response object**, which should be the case in the first place instead of relying on PHP environment settings.

> You can use [juliangut/cacheware](https://github.com/juliangut/cacheware) which will automatically set the corrent session ini settings and add the corresponding cache headers to response object.

By using `session_regenerate_id()` during execution cryptographically secure session ID will be replaced by default PHP `session.hash_function` generated ID (not really secure). To prevent this from happening use `\Jgut\Middleware\Session` helper method `regenerateSessionId()` instead:

```
\Jgut\Middleware\Session::regenerateSessionId();
```

Installation
------------

[](#installation)

### Composer

[](#composer)

```
composer require juliangut/sessionware

```

Usage
-----

[](#usage)

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

use \Jgut\Middleware\SessionWare

$configuration = [
  'name' => 'myProjectSessionName',
  'lifetime' => 1800, // 30 minutes
];

$sessionMiddleware = new SessionWare($configuration);

// Get $request and $response from PSR7 implementation
$request = new Request();
$response = new Response();

$response = $sessionMiddleware($request, $response, function() { });

// Session is started, populated with default parameters and response has session cookie header
```

Integrated on a Middleware workflow:

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

use \Jgut\Middleware\SessionWare

$configuration = [
  'name' => 'myProjectSessionName',
  'lifetime' => SessionWare::SESSION_LIFETIME_NORMAL, // 15 minutes
];
$defaultSessionParams = [
  'default_timezone' => 'UTC',
]

$app = new \YourMiddlewareAwareApplication();
$app->addMiddleware(new SessionWare($configuration, $defaultParameters));
$app->run();
```

#### Session helper

[](#session-helper)

There is an extra Session helper to abstract access to the $\_SESSION variable. This is usefull for example when NOT accessing global variables is important for you (such as when using PHP\_MD to statically analise your code)

In order to benefit from SessionWare cryptographically secure generated session id DO use

```
$session = new \Jgut\Middleware\Session;
$session->regenerate();

// Or can be called statically
\Jgut\Middleware\Session::regenerateSessionId()

```

### Config

[](#config)

```
$sessionMiddleware = new SessionWare([
  'timeoutKey' => '__SESSIONWARE_TIMEOUT_TIMESTAMP__'
  'name' => 'SessionWareSession',
  'savePath' => '/tmp/SessionWareSession',
  'lifetime' => SessionWare::SESSION_LIFETIME_NORMAL,
  'domain' => 'http://example.com',
  'path' => '/',
  'secure' => false,
  'httponly' => true,
]);
```

> Default values mimic those provided by default PHP installation so the middleware can be used as a direct drop-in with automatic session timeout control

#### timeoutKey

[](#timeoutkey)

Parameter stored in session array to control session validity according to `lifetime` parameter. Defaults to

```
\Jgut\Middleware\SessionWare::SESSION_TIMEOUT_KEY_DEFAULT = '__SESSIONWARE_TIMEOUT_TIMESTAMP__';

```

*It is advised not to change this value unless it conflicts with one of your own session keys (which is unlikely if not directly impossible)*

#### name

[](#name)

Assigns session name, default PHP `PHPSESSID` session name will be used if none provided.

> Review Important note below.

#### savePath

[](#savepath)

This configuration is used only if default 'files' session save handler is selected in `session.save_handler`.

Assigns the path to store session files. If none provided `sys_get_temp_dir()`, `session_save_path()` and session 'name' will be used to compose a unique path.

> Review Important note below.

#### lifetime

[](#lifetime)

Number of seconds for the session to be considered valid. uses `session.gc_maxlifetime` and `session.cookie_lifetime` to discover PHP configured session lifetime if none provided. Finally it defaults to `SessionWare::SESSION_LIFETIME_DEFAULT` (24 minutes) if previous values are not available or their value is zero.

There are six session lifetime constants available for convenience:

- SESSION\_LIFETIME\_FLASH = 5 minutes
- SESSION\_LIFETIME\_SHORT = 10 minutes
- SESSION\_LIFETIME\_NORMAL = 15 minutes
- SESSION\_LIFETIME\_DEFAULT = 24 minutes
- SESSION\_LIFETIME\_EXTENDED = 1 hour
- SESSION\_LIFETIME\_INFINITE = `PHP_INT_MAX`, around 1145 years on x86\_64 architecture

#### path, domain, secure and httponly

[](#path-domain-secure-and-httponly)

Shortcuts to `session.cookie_path`, `session.cookie_domain`, `session.cookie_secure` and `session.cookie_httponly`. If not provided configured cookie params will be used, so can be set using `session_set_cookie_params()` before middleware run.

Events
------

[](#events)

You can listen to timeout events to perform actions accordingly. There are currently two events

- `pre.session_timeout` triggered right before session is wiped when session timeout is reached
- `post.session_timeout` triggered right after session has been restarted due to session timeout

Events provide sessionId as parameter:

```
$sessionware = new SessionWare($configuration);
$sessionware->addListener('pre.session_timeout', function($sessionId) {
    echo sprintf('session "%s" timed out', $sessionId);
})
$sessionware->addListener('post.session_timeout', function($sessionId) {
    echo sprintf('new session "%s" created', $sessionId);
})
```

Important note
--------------

[](#important-note)

### Using default 'files' session save handler

[](#using-default-files-session-save-handler)

If you define a session 'lifetime' you **MUST** set a session 'savePath' or a session 'name' (different to `PHPSESSID`). This is to separate session files from other PHP scripts session files, for the garbage collector to handle expired files removal correctly.

Be aware that if this condition is not met starting a session might remove session files from other script/application as they are all located in the same directory and there is no way for the garbage collector to tell which script/application they belong to.

### Using custom session save handler

[](#using-custom-session-save-handler)

Distinguishing between different script/application session files shouldn't be a problem in this case. But be carefull not to send cookie headers (`setcookie`) directly to the client but to include them in the response object instead.

Register your custom session save handler *before* running this middleware to prevent savePath to be created.

Contributing
------------

[](#contributing)

Found a bug or have a feature request? [Please open a new issue](https://github.com/juliangut/sessionware/issues). Have a look at existing issues before.

See file [CONTRIBUTING.md](https://github.com/juliangut/sessionware/blob/master/CONTRIBUTING.md)

License
-------

[](#license)

See file [LICENSE](https://github.com/juliangut/sessionware/blob/master/LICENSE) included with the source code for a copy of the license terms.

###  Health Score

28

—

LowBetter than 54% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity12

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity63

Established project with proven stability

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 ~62 days

Recently: every ~86 days

Total

7

Last Release

3299d ago

Major Versions

0.2 → 1.02016-05-22

1.2.1 → 2.x-dev2017-05-02

PHP version history (2 changes)0.1PHP >=5.5

2.x-devPHP ^7.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/4c50421f1ab4148354dc2dd5dcaba168656b17ea913b310d112deb39a6f73ca1?d=identicon)[juliangut](/maintainers/juliangut)

---

Tags

middlewarepsr7session

###  Code Quality

TestsPHPUnit

Code StylePHP\_CodeSniffer

### Embed Badge

![Health badge](/badges/juliangut-sessionware/health.svg)

```
[![Health](https://phpackages.com/badges/juliangut-sessionware/health.svg)](https://phpackages.com/packages/juliangut-sessionware)
```

###  Alternatives

[akrabat/ip-address-middleware

PSR-15 middleware that determines the client IP address and stores it as a ServerRequest attribute

1702.5M18](/packages/akrabat-ip-address-middleware)[compwright/php-session

Standalone session implementation that does not rely on the PHP session module or the $\_SESSION global, ideal for ReactPHP applications

189.4k](/packages/compwright-php-session)[yiisoft/session

A session service, PSR-15 session middleware, and a flash message service which helps use one-time messages.

20311.6k13](/packages/yiisoft-session)[akrabat/proxy-detection-middleware

PSR-7/PSR-15 Middleware that determines the scheme, host and port from the 'X-Forwarded-Proto', 'X-Forwarded-Host' and 'X-Forwarded-Port' headers and updates the Request's Uri object.

3190.4k1](/packages/akrabat-proxy-detection-middleware)[phps-cans/psr7-middleware-graphql

This package contains a http-interop middleware implementation to handle graphql request

1528.7k](/packages/phps-cans-psr7-middleware-graphql)[mtymek/blast-base-url

PSR-7 middleware and helpers for working with base URL.

1054.0k3](/packages/mtymek-blast-base-url)

PHPackages © 2026

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