Flarum Redis Laravel Package

Getting Started

1. Confirm the extension is compatible with your Flarum major version and install it the way Flarum expects (composer require bokt/flarum-redis, then enable it in the admin if it is exposed as an extension; otherwise it just registers service providers).
2. Make sure Redis is actually reachable before touching Flarum:

   redis-cli -h 127.0.0.1 -p 6379 ping   # -> PONG
   

3. Add the connection details to config.php (Flarum reads this file per request; there is no Laravel-style config cache to clear):

   'redis' => [
       'host'     => '127.0.0.1',
       'port'     => 6379,
       'database' => 0,
       'password' => null,
   ],
   'cache' => [
       'driver' => 'redis',
   ],
   'queue' => [
       'driver'     => 'redis',
       'connection' => 'default',
   ],
   

4. Verify the switch: flush the app cache (php flarum cache:clear) and check Redis for Flarum keys (redis-cli --scan --pattern 'flarum*'). If keys appear, the cache side is live.
5. First real use case: move email/notification delivery off the request cycle. With the Redis queue configured, Flarum's notification and email jobs stop blocking page loads, and you run a worker:

   php flarum queue:work
   

   Put that under Supervisor/systemd in any real deployment.

Look first at config.php, then at the extension's service providers (extend.php / src/) to see exactly which cache store and queue connection names it binds. That tells you what strings are valid for cache.driver and queue.connection in your version.

Implementation Patterns

• Cache is transparent to app code. You generally do not call a special API — Flarum's own caching goes through the store. Extension code should keep using Flarum's cache abstraction (resolve(Flarum\Cache\Cache::class) or the Cache facade) so it keeps working on file or Redis interchangeably.
• Queue pattern for custom work. Push long-running work as jobs instead of doing it inline:

  resolve('Illuminate\Contracts\Bus\Dispatcher')->dispatch(new ReindexDiscussion($id));
  

  Keep jobs serializable and idempotent — workers retry.
• Separate logical databases/prefixes. Use different Redis DB indexes (or key prefixes) for cache vs. queue in multi-app or staging-on-same-Redis setups, so FLUSHDB or a cache:clear never nukes queued jobs.
• Multi-node pattern. Once the queue and cache live in Redis, you can run several PHP-FPM/web containers behind a load balancer; sessions are DB-backed in Flarum, and cache/queue no longer assume local disk.
• Worker management. Run php flarum queue:work --tries=3 --timeout=90 under a process manager, scale workers horizontally for bursts (e.g., mass email), and php flarum queue:restart as a deploy hook so workers reload code.
• Failover-friendly config. Point cache at Redis but keep an eye on the queue: if you want the forum to survive Redis downtime, you can leave cache on file and only move queue — partial adoption is a valid rollout.

Gotchas and Tips

• Version compatibility is the big one. This is a small (14★) package; pin it in composer.json and test upgrades of Flarum separately. If cache.driver/queue.connection keys don't match what the provider expects, you silently fall back to defaults rather than erroring.
• Config lives in config.php, not .env. Flarum doesn't read Laravel .env for these. Putting Redis settings in the wrong place is the most common "it didn't switch" cause.
• After deploying new job code, always php flarum queue:restart. Long-running workers keep the old code in memory and will fail on changed job constructors.
• Serialization bites. Redis queue payloads are serialized; jobs holding Eloquent models or un-serializable resources (closures, PDO handles, UploadedFile) will fail at dispatch or on the worker. Pass IDs and reload inside the job.
• cache:clear scope. Confirm what the extension's clear actually flushes. If Flarum and other apps share a Redis DB, prefer dedicated DB indexes or a key prefix rather than broad flushes.
• Redis down = forum down (usually). The Redis cache store doesn't fall back to file. If you can't tolerate Redis outages, keep cache on file and only queue in Redis, or run Redis with persistence/replicas.
• Auth quirks. A non-null password with a blank username is a frequent connection failure; check redis-cli -a <pw> ping with the exact credentials.
• Not a drop-in for Redis Cluster/Sentinel unless the underlying client supports it — verify before assuming HA. For Sentinel, you typically need to supply the concrete connection config the provider reads.
• Debugging toolkit: redis-cli monitor to see live commands during a request, redis-cli --scan --pattern 'flarum*' to inspect keys, and the worker's foreground output (queue:work without a daemon) to surface job exceptions.
• Extension point: if you need a custom connection (e.g., a non-default Redis instance), bind it in your own service provider and point queue.connection / cache at that name rather than editing the vendor package.