Redis Laravel Package

Getting Started

Install and enable

composer require fof/redis
php flarum extension:enable fof-redis
php flarum cache:clear

Where to look first

1. Admin → Extensions → Redis — this is the entire control surface. You get toggles for the cache driver and the queue driver, plus connection fields (host, port, password, database index, prefix).
2. config.php at the Flarum root — after enabling, confirm the cache/queue blocks reflect Redis. This file is the source of truth for bootstrapping; if the extension and config.php disagree, config.php usually wins at boot time.
3. php flarum info — sanity-check the active cache/queue drivers and extension version after enabling.
4. redis-cli — PING, INFO keyspace, and MONITOR are your fastest feedback loop.

First use case

The canonical win is moving Flarum's file-based cache to Redis so cache entries are shared across multiple app servers (load-balanced or containerised deployments) and so tagged cache invalidation behaves consistently. The second win is the queue: enabling the Redis queue driver lets you push expensive work (notifications, email, search indexing, image processing jobs from other extensions) off the request thread and onto a php flarum queue:work process.

Start with cache only, run it for a day, confirm the forum boots and pages are served from Redis (redis-cli MONITOR shows GET/SET traffic), then enable the queue driver and stand up a worker.

Implementation Patterns

Cache-only rollout (recommended first step)

Enable the cache toggle, set host/port/database (e.g. db 1 for cache), leave the queue toggle off. Flarum will keep using its default sync queue, but every cache read/write now hits Redis. Verify with:

redis-cli -n 1 DBSIZE
redis-cli -n 1 --scan --pattern '*flarum*' | head

Queue-only rollout

If you already have a fast cache (e.g. APCu or file on a single node) but want async jobs, enable only the queue toggle and point it at a separate database index (db 2). Then run a supervised worker:

; /etc/supervisor/conf.d/flarum-queue.conf
[program:flarum-queue]
command=php /var/www/flarum flarum queue:work --sleep=3 --tries=3 --timeout=120
directory=/var/www/flarum
user=www-data
autostart=true
autorestart=true
numprocs=2
stopasgroup=true
killasgroup=true

Restart workers on every deploy (supervisorctl restart flarum-queue:*) so they pick up new code — long-lived PHP processes do not reload classes.

Separate databases per concern

The single most useful pattern: use distinct Redis DB indexes for cache, queue, and any custom app data. It makes FLUSHDB safe and keeps key counts interpretable.

Set the prefix in the extension settings if provided; otherwise configure it via the Redis connection options.

Reusing the connection for custom code

Because Flarum is built on Illuminate components, once the Redis connection is configured you can use the Redis facade from your own extension for counters, rate limits, or locks:

use Illuminate\Support\Facades\Redis;

Redis::incr("throttle:{$userId}:" . now()->format('YmdHi'));
Redis::expire("throttle:{$userId}:" . now()->format('YmdHi'), 60);

// Atomic lock — useful for one-off migrations or cron guards
$lock = Redis::set('lock:daily-digest', '1', 'NX', 'EX', 300);
if ($lock) {
    // run the digest
}

Deploy workflow

php flarum cache:clear        # clears Flarum cache (tagged/namespaced)
php flarum migrate
supervisorctl restart flarum-queue:*

Avoid redis-cli FLUSHALL in production; use FLUSHDB per-index or targeted SCAN+DEL if you must purge.

Multi-tenant / multi-site

Give each Flarum instance its own database index and its own key prefix. Two sites sharing db 0 without distinct prefixes will eventually collide and produce baffling cache bleed (one site's settings cache served to another).

Gotchas and Tips

Cache clear does not mean flush. php flarum cache:clear empties Flarum's cache namespace; it does not wipe the Redis DB. If you're debugging stale data, check DBSIZE and inspect keys directly — leftovers from old prefixes can survive.

PHP Redis extension vs Predis. Flarum's Illuminate Redis layer supports both phpredis (ext-redis) and predis/predis. ext-redis is faster but must be installed and enabled in every PHP SAPI (web and CLI — the queue worker uses CLI). If the CLI SAPI lacks the extension, the worker fails while the web frontend works fine. Verify with:

php -m | grep -i redis
php -r 'var_dump(class_exists("Redis"));'

Queue without a worker is a silent failure. Enabling the Redis queue driver while nothing consumes it means jobs accumulate in Redis forever — emails don't send, notifications don't fire. There is no visible error; the forum just "stops doing things." Add a monitor/alert on LLEN of the queue list.

Redis down = forum down (or very slow). If the cache driver is Redis and the server is unreachable, Flarum's boot path can fail or hang with connection timeouts. Keep config.php accessible so you can flip the cache driver back to file as an emergency rollback. Consider setting short connect timeouts in the Redis options if the extension exposes them.

Settings are read during boot. The admin settings for host/port are stored in the database — but Redis config is needed to bootstrap. This creates a chicken-and-egg on fresh installs or after a DB restore: the extension may fall back to defaults until the settings cache is repopulated. If behaviour looks stale after a restore, run php flarum cache:clear and reload the admin page.

Changing settings may not take effect until workers restart. The queue worker holds its own connection options in memory; update host/password in the admin UI and you must restart the supervisor program, not just reload the page.

Password and TLS edge cases. Passwords containing @, :, /, or # break naive connection-string assembly — prefer explicit host/port/password fields over a URL. For managed Redis (AWS ElastiCache, Upstash, DigitalOcean) you often need rediss:// (TLS) or a unix socket; check whether the extension exposes a scheme/socket field before assuming plain TCP.

Serialisation pitfalls in queued jobs. Jobs dispatched to Redis are serialised. Flarum jobs that capture closures, request objects, or Eloquent models with stale state will fail on the worker with Serialization of 'Closure' is not allowed or ModelNotFoundException. Pass IDs, not models, into jobs from your own extensions.

Cache tags are why Redis matters. Laravel's Redis store supports cache tags, so tagged invalidation (Flarum uses this for settings, permissions, etc.) becomes cheap and correct. File/database stores emulate tags poorly. If you're migrating from file cache and seeing stale permissions after role changes, Redis cache is the actual fix.

Memory policy matters. Redis as a cache should typically run allkeys-lru (or volatile-lru) — but if that same instance also holds queue data, eviction will silently delete pending jobs. Rule: queue DB on a noeviction policy, cache DB on lru. Separate instances if you can afford it.

Debugging playbook.

redis-cli -n 1 MONITOR          # live commands; noisy but definitive
redis-cli -n 1 INFO keyspace    # keys per DB, expirations
redis-cli -n 2 LLEN <queue-key> # pending jobs
redis-cli -n 2 LRANGE <queue-key> 0 5   # inspect a few payloads
tail -f storage/logs/flarum-*.log

MONITOR on production is a performance hit — use it briefly.

Low-maturity caveat. This is a small, single-maintainer package (3 stars, no dependents). Read the source — it's a thin wrapper over Flarum's config and Illuminate's Redis connector, so the blast radius of a bug is limited but so is the test coverage. Pin the version in composer.json, test upgrades in staging, and keep a documented one-line rollback (flip config.php back to file/sync and restart PHP-FPM).

Extension points. Because the extension ultimately rebinds Flarum's cache/queue bindings, you can override behaviour from your own extension's service provider — e.g. wrap the cache repository with a decorator for logging, or register a custom queue connector. Look at the extension's service provider for the binding names it replaces; those are your hooks.