PHPackages                             uma/redis-session-handler - 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. [Caching](/categories/caching)
4. /
5. uma/redis-session-handler

ActiveLibrary[Caching](/categories/caching)

uma/redis-session-handler
=========================

An alternative Redis session handler

v0.9.9(4y ago)120209.4k—1%25[1 issues](https://github.com/1ma/RedisSessionHandler/issues)MITPHPPHP >=5.6CI failing

Since Jan 24Pushed 4y ago9 watchersCompare

[ Source](https://github.com/1ma/RedisSessionHandler)[ Packagist](https://packagist.org/packages/uma/redis-session-handler)[ RSS](/packages/uma-redis-session-handler/feed)WikiDiscussions master Synced 1mo ago

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

RedisSessionHandler
===================

[](#redissessionhandler)

[![Build Status](https://github.com/1ma/RedisSessionHandler/workflows/.github/workflows/ci.yml/badge.svg)](https://github.com/1ma/RedisSessionHandler/actions)[![Latest Stable Version](https://camo.githubusercontent.com/73e5c8e661e3f20306b937e5712694041ce5f8d024ef8ca5a9edd155555e2bae/68747470733a2f2f706f7365722e707567782e6f72672f756d612f72656469732d73657373696f6e2d68616e646c65722f762f737461626c65)](https://packagist.org/packages/uma/redis-session-handler)[![Monthly Downloads](https://camo.githubusercontent.com/4e64964fe9d1f81f4a8e85fffeabd0df64976625c6a5350614922417dd0dd9e5/68747470733a2f2f706f7365722e707567782e6f72672f756d612f72656469732d73657373696f6e2d68616e646c65722f642f6d6f6e74686c79)](https://packagist.org/packages/uma/redis-session-handler)

An alternative Redis session handler featuring session locking and session fixation protection.

News
----

[](#news)

- phpredis v4.1.0 (released on 2018-07-10) added support for session locking, but it is disabled by default. To enable it you must set the new `redis.session.locking_enabled` INI directive to `true`. This version is the first to pass the test in `ConcurrentTest` that stresses the locking mechanism.

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

[](#installation)

RedisSessionHandler requires PHP >=5.6 with the phpredis extension enabled and a Redis >=2.6 endpoint. Add [`uma/redis-session-handler`](https://packagist.org/packages/uma/redis-session-handler) to the `composer.json` file:

```
$ composer require uma/redis-session-handler

```

Overwrite the default session handler with `UMA\RedisSessionHandler` before your application calls any `session_` function. If you are using a framework and unsure when or where that happens, a good rule of thumb is "as early as possible". A safe bet might be the frontend controller in the public directory of the project or an equivalent initialization script.

```
// top of my-project/web/app.php

require_once __DIR__ . '/../vendor/autoload.php';

session_set_save_handler(new \UMA\RedisSessionHandler(), true);
```

Note that calling `session_set_save_handler` overwrites any value you might have set in the `session.save_handler` option of the php.ini file, so you don't need to change that. However, RedisSessionHandler still uses `session.save_path` to find the Redis server, just like the vanilla phpredis session handler:

```
; examples
session.save_path = "localhost"
session.save_path = "localhost?timeout=2.5"
session.save_path = "tcp://1.2.3.4:5678?prefix=APP_SESSIONS:&database=2"
session.save_path = "unix:///var/run/redis.sock"
session.save_path = "/var/run/redis.sock?database=2"
```

Available query params:

- `timeout` (float), default `0.0`, which means unlimited timeout
- `prefix` (string), default `'PHPREDIS_SESSION:'`
- `auth` (string), default `null`
- `database` (int), default `0`

Currently only a single host definition is supported.

Note than when connecting through a Unix socket the timeout is ignored.

Known Caveats
-------------

[](#known-caveats)

### Using RedisSessionHandler with the `max_execution_time` directive set to `0` is not recommended

[](#using-redissessionhandler-with-the-max_execution_time-directive-set-to-0-is-not-recommended)

Whenever it can, the handler uses the `max_execution_time` directive as a hard timeout for the session lock. This is a last resort mechanism to release the session lock even if the PHP process crashes and the handler fails to do it itself.

When `max_execution_time` is set to `0` (meaning there is no maximum execution time) this kind of hard timeout cannot be used, as the lock must be kept for as long as it takes to run the script, which is an unknown amount of time. This means that if for some unexpected reason the PHP process crashes and the handler fails to release the lock there would be no safety net and you'd end up with a dangling lock that you'd have to detect and purge by other means.

So when using RedisSessionHandler it is advised *not* to disable `max_execution_time`.

### RedisSessionHandler does not support `session.use_trans_sid=1` nor `session.use_cookies=0`

[](#redissessionhandler-does-not-support-sessionuse_trans_sid1-nor-sessionuse_cookies0)

When these directives are set this way PHP switches from using cookies to passing the session ID around as a query param.

RedisSessionHandler cannot work in this mode. *This is by design*.

### RedisSessionHandler ignores the `session.use_strict_mode` directive

[](#redissessionhandler-ignores-the-sessionuse_strict_mode-directive)

Because running PHP with strict mode disabled (which is the default!) does not make any sense whatsoever. RedisSessionHandler only works in strict mode. The *Session fixation* section of this README explains what that means.

Motivation
----------

[](#motivation)

The Redis session handler bundled with [phpredis](https://github.com/phpredis/phpredis) has had a couple of rather serious bugs for years, namely the [lack of per-session locking](https://github.com/phpredis/phpredis/issues/37) and the [impossibility to protect against session fixation attacks](https://github.com/phpredis/phpredis/issues/1033).

This package provides a compatible session handler built on top of the Redis extension that is not affected by these issues.

### Session Locking explained

[](#session-locking-explained)

In the context of PHP, "session locking" means that when multiple requests with the same session ID hit the server roughly at the same time, only one gets to run while the others get stuck waiting inside `session_start()`. Only when that first request finishes or explicitly runs [`session_write_close()`](http://php.net/manual/en/function.session-write-close.php), one of the others can move on.

When a session handler does not implement session locking concurrency bugs might start to surface under heavy traffic. I'll demonstrate the problem using the default phpredis handler and this simple script:

```