PHPackages                             fof/redis - 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. fof/redis

ActiveLibrary[Caching](/categories/caching)

fof/redis
=========

Adds Redis cache, sessions and queue to Flarum

v1.1.6(5mo ago)411.7k↑33.7%1[2 issues](https://github.com/FriendsOfFlarum/redis/issues)3MITPHPCI passing

Since Feb 15Pushed 3w ago1 watchersCompare

[ Source](https://github.com/FriendsOfFlarum/redis)[ Packagist](https://packagist.org/packages/fof/redis)[ Docs](https://friendsofflarum.org)[ Fund](https://opencollective.com/fof/donate)[ RSS](/packages/fof-redis/feed)WikiDiscussions 2.x Synced 1w ago

READMEChangelog (10)Dependencies (11)Versions (29)Used By (3)

Redis sessions, cache, queues & settings
============================================

[](#redis-sessions-cache-queues--settings)

This library allows using Redis as cache, session, settings storage, and for the queue. You can only enable these services by using a local extender (the `extend.php` in the root of your Flarum installation). See the "Set up" section below.

> This is an advanced utility for webmasters!

### Installation

[](#installation)

Install manually with composer:

```
composer require fof/redis:"*"
```

### Set up

[](#set-up)

In your `extend.php`:

```
return [
    new FoF\Redis\Extend\Redis([
        'host' => '127.0.0.1',
        'password' => null,
        'port' => 6379,
        'database' => 1
    ])
];
```

This enables sessions, cache, settings, and queue to run on redis.

#### phpredis vs Predis

[](#phpredis-vs-predis)

If the PHP `redis` extension (`ext-redis`) is installed, it will be used automatically. Otherwise Predis is used as a fallback. No configuration change is required.

**Persistent connections (recommended for phpredis)**

With phpredis, connections can be reused across requests within the same PHP-FPM worker process. Add `persistent` and `persistent_id` to your config to enable this:

```
return [
    new FoF\Redis\Extend\Redis([
        'host'          => '127.0.0.1',
        'password'      => null,
        'port'          => 6379,
        'database'      => 1,
        'persistent'    => true,
        'persistent_id' => 'flarum',  // groups connections into a named pool per worker
    ])
];
```

This avoids opening a new TCP connection on every request, which is a significant throughput improvement at scale. `persistent_id` is a string used to key the connection slot — use the same value across all workers on the same host.

**Unix socket**

```
return [
    new FoF\Redis\Extend\Redis([
        'host'          => '/var/run/redis/redis.sock',
        'port'          => 0,
        'database'      => 1,
        'persistent'    => true,
        'persistent_id' => 'flarum',
    ])
];
```

**Other phpredis options**

KeyExampleNotes`timeout``2.0`Connect timeout in seconds`read_timeout``2.0`Per-command timeout`retry_interval``100`ms between reconnect attempts`prefix``'flarum_'`Key prefix`compression``Redis::COMPRESSION_LZ4`phpredis ≥ 5.3, requires lz4/zstd compiled into ext-redis> **Multi-instance deployments:** This extension can handle distributed cache invalidation across multiple Flarum instances (pods/containers) via Redis Pub/Sub. See [DISTRIBUTED\_CACHE.md](DISTRIBUTED_CACHE.md) for details.

#### Settings Cache

[](#settings-cache)

This extension includes a **settings cache** that significantly improves performance by caching all Flarum settings in Redis. This eliminates hundreds to thousands of database queries per page load.

**How it works:**

- All settings are cached in Redis with a dedicated connection (database 4 by default)
- Settings are loaded from cache on first access, then served from memory
- Cache is invalidated on any settings write, ensuring consistency across multiple instances
- Perfect for multi-container/multi-pod deployments where settings changes must propagate immediately

**Configuration:**

The settings cache uses database 4 by default. To customize:

```
return [
    (new FoF\Redis\Extend\Redis([
        'host' => '127.0.0.1',
        'password' => null,
        'port' => 6379,
        'database' => 1,
    ]))
    ->useDatabaseWith('cache', 1)
    ->useDatabaseWith('queue', 2)
    ->useDatabaseWith('session', 3)
    ->useDatabaseWith('settings', 4)  // Settings cache database
];
```

To use a completely separate Redis instance for settings:

```
return [
    (new FoF\Redis\Extend\Redis([
        'connections' => [
            'cache' => [
              'host' => 'cache.yoursite.com',
              'database' => 1,
            ],
            'settings' => [
              'host' => 'settings.yoursite.com',
              'database' => 4,
            ],
            // ... other connections
        ],
    ]))
];
```

**Performance impact:**

- Reduces settings-related database queries by 97-99%
- Typical Flarum page load: 1,500+ settings queries → ~10 queries
- Cache invalidation ensures consistency in multi-instance environments

> See "Use different database for each service" below to split up the database for cache vs sessions, queue because a cache clear action will clear sessions and queue jobs as well if they share the same database.

#### Advanced configuration

[](#advanced-configuration)

1. Disable specific services:

```
return [
    (new FoF\Redis\Extend\Redis([
        'host' => '127.0.0.1',
        'password' => null,
        'port' => 6379,
        'database' => 1,
    ]))->disable(['cache', 'queue', 'settings'])
];
```

2. Use different database for each service:

```
return [
    (new FoF\Redis\Extend\Redis([
        'host' => '127.0.0.1',
        'password' => null,
        'port' => 6379,
        'database' => 1,
    ]))
    ->useDatabaseWith('cache', 1)
    ->useDatabaseWith('queue', 2)
    ->useDatabaseWith('session', 3)
    ->useDatabaseWith('settings', 4)
];
```

3. Completely separate the config array:

```
return [
    (new FoF\Redis\Extend\Redis([
        'connections' => [
            'cache' => [
              'host' => 'cache.int.yoursite.com',
              'password' => 'foo-bar',
              'port' => 6379,
              'database' => 1,
            ],
            'queue' => [
              'host' => 'queue.int.yoursite.com',
              'password' => 'foo-bar',
              'port' => 6379,
              'database' => 1,
            ],
            'session' => [
              'host' => 'session.int.yoursite.com',
              'password' => 'foo-bar',
              'port' => 6379,
              'database' => 1,
            ],
            'settings' => [
              'host' => 'settings.int.yoursite.com',
              'password' => 'foo-bar',
              'port' => 6379,
              'database' => 4,
            ],
        ],
    ]))
];
```

4. Use a cluster:

```
return [
    (new FoF\Redis\Extend\Redis([
        'host' => '127.0.0.1',
        'password' => null,
        'port' => 6379,
        'database' => 1,
        'options' => [
          'replication' => 'sentinel',
          'service' => 'mymaster:26379',
        ]
    ]))
    ->useDatabaseWith('cache', 1)
    ->useDatabaseWith('queue', 2)
    ->useDatabaseWith('session', 3)
    ->useDatabaseWith('settings', 4)
];
```

#### Queue

[](#queue)

Make sure to start your queue workers, see the [laravel documentation](https://laravel.com/docs/13.x/queues#running-the-queue-worker) for specifics. To test the worker can start use `php flarum queue:work`.

##### Queue options

[](#queue-options)

The queue allows for several options to be added, retry\_after, block\_for and after\_commit. You can set these by adding a `queue` array in the configuration:

```
return [
    (new FoF\Redis\Extend\Redis([
        'host' => '127.0.0.1',
        'password' => null,
        'port' => 6379,
        'database' => 1,
        'queue' => [
            'retry_after' => 120, // seconds
            'block_for' => 5, // seconds
            'after_commit' => true,
            'failed_ttl' => 604800, // seconds; how long to keep failed jobs (default 7 days)
            'queues' => ['default'], // additional named queues (see below)
        ]
    ]))
    ->useDatabaseWith('cache', 1)
    ->useDatabaseWith('queue', 2)
    ->useDatabaseWith('session', 3)
];
```

You can read up on the meaning of `retry_after`, `block_for` and `after_commit` in the [Laravel Documentation](https://laravel.com/docs/13.x/queues#redis).

##### Named queues

[](#named-queues)

Like Laravel Horizon, the Redis queue supports **multiple named queues**, which let you separate and prioritise work — for example a fast `notifications` queue that should never be held up behind slow `exports`.

Jobs are routed to a queue by name. A job can set its own target with the core `AbstractJob::$onQueue` property (or Laravel's `onQueue()` method):

```
class SendExportJob extends \Flarum\Queue\AbstractJob
{
    public static ?string $onQueue = 'exports';
}
```

You then run a worker across the queues you care about, in **priority order** — the worker fully drains each queue before moving to the next:

```
php flarum queue:work --queue=notifications,default,exports
```

Because Redis has no efficient way to list every queue that exists, Flarum keeps a registry of the queue names admin tooling should know about (the queue dashboard and per-queue pause read it). Declare the extra queues your site uses in the `queues` config key so they are covered:

```
'queue' => [
    'queues' => ['notifications', 'exports'],
],
```

`default` is always included automatically, so you only need to list the additional names. Queues you don't declare still work — jobs pushed to them are processed normally — but they won't appear in the dashboard or be individually pausable.

##### Failed jobs

[](#failed-jobs)

When the queue runs on Redis, failed jobs are stored **in Redis** rather than in the database. Flarum core only records failed jobs in the database for the database queue driver; with this extension enabled, your failures stay on Redis so they don't add load or writes to your database. They remain fully visible and manageable from the admin queue dashboard (view, retry, and delete), and via the `php flarum queue:failed`, `queue:retry` and `queue:forget` commands.

Failed jobs are given a time-to-live so they don't accumulate forever, controlled by `failed_ttl` (seconds) in the `queue` config above. It defaults to **7 days** (`604800`). Set it to `0` or `null` to keep failed jobs until they are retried or deleted. Because these entries carry a TTL, they are also eligible for eviction first under a `volatile-*` `maxmemory-policy`, so a memory-constrained Redis reclaims old failure records before touching live queue jobs.

### Migrating from `blomstra/flarum-redis`

[](#migrating-from-blomstraflarum-redis)

Simply update the namespace used in your `extend.php` file from `Blomstra\Redis...` to `FoF\Redis...`

### Updating

[](#updating)

```
composer update fof/redis
```

### FAQ

[](#faq)

*Why are there still files in storage/cache?*Some code still relies on physical files being present. This includes the formatter cache and the view caches.

### Links

[](#links)

- [Packagist](https://packagist.org/packages/fof/redis)
- [GitHub](https://github.com/FriendsOfFlarum/redis)

###  Health Score

46

—

FairBetter than 92% of packages

Maintenance75

Regular maintenance activity

Popularity31

Limited adoption so far

Community19

Small or concentrated contributor base

Maturity49

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 52.7% 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 ~25 days

Recently: every ~36 days

Total

22

Last Release

21d ago

Major Versions

v1.1.0-beta.2 → v2.0.0-beta.32026-01-14

v1.1.1 → v2.0.0-beta.42026-02-21

v1.1.2 → v2.0.0-beta.62026-02-21

v1.1.4 → v2.0.0-beta.72026-03-02

v1.1.6 → v2.0.0-beta.82026-03-07

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/16573496?v=4)[IanM](/maintainers/imorland)[@imorland](https://github.com/imorland)

![](https://avatars.githubusercontent.com/u/1630413?v=4)[Gregor Hammerschmidt](/maintainers/GreXXL)[@GreXXL](https://github.com/GreXXL)

![](https://www.gravatar.com/avatar/0538135c1debcef5602dce7ece027909cc832b7a6284ab9189a19aa8de98d60d?d=identicon)[clarkwinkelmann](/maintainers/clarkwinkelmann)

![](https://www.gravatar.com/avatar/1298cdc0b2402a1aa34fb75a254947d655e090d62bd0531311331d369cac934e?d=identicon)[datitisev](/maintainers/datitisev)

---

Top Contributors

[![imorland](https://avatars.githubusercontent.com/u/16573496?v=4)](https://github.com/imorland "imorland (29 commits)")[![luceos](https://avatars.githubusercontent.com/u/504687?v=4)](https://github.com/luceos "luceos (26 commits)")

---

Tags

rediscachequeuesession

### Embed Badge

![Health badge](/badges/fof-redis/health.svg)

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

###  Alternatives

[yangusik/laravel-balanced-queue

Laravel queue management with load balancing between partitions (user groups)

8516.9k](/packages/yangusik-laravel-balanced-queue)[flarum-lang/russian

Russian language pack for Flarum.

13129.1k](/packages/flarum-lang-russian)[pdffiller/qless-php

PHP Bindings for qless

29113.7k2](/packages/pdffiller-qless-php)

PHPackages © 2026

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