Flarum Redis Laravel Package

Getting Started

This is a Flarum package, not a Laravel application package — but if you're coming from Laravel, almost everything below will feel familiar. It wires Illuminate-style Redis drivers for cache, session, and queue into Flarum's service container. The moving parts (prefixes, queue workers, failed jobs, retry_after) are the same concepts you already know; only the bootstrapping differs.

Minimal path:

1. Install the package

   composer require blomstra/flarum-redis
   

2. Make sure a Redis client exists. ext-redis (phpredis) is preferred. If you can't install the extension, add predis/predis and configure the client as predis.
3. Enable it as a Flarum extension. Driver packages still have to be enabled:

   php flarum extension:enable blomstra-redis
   

   Confirm with php flarum info (it lists enabled extensions).
4. Configure config.php in the project root. This is the first place to look, and it's where the entire package is controlled. Depending on version, connection details are either inline under each driver or under a top-level redis key — check the README and the small vendor/blomstra/flarum-redis/src tree before copying snippets from blog posts.
5. First use case: move the cache and session drivers off the filesystem to get consistent state across web nodes and less disk churn, then move the queue to Redis so php flarum queue:work handles notification/email/image jobs quickly instead of via the sync driver.

Verify with redis-cli ping, then load the forum with redis-cli MONITOR running in another terminal. You should see GET/SET/EXPIRE traffic against prefixed keys on a normal page load.

Implementation Patterns

Treat this as a config-driven package: there's no settings UI beyond enabling it, and no application code to write for the core use case. Day-to-day leverage comes from how you structure the config and how you run the worker.

Separate cache, session, and queue. Use distinct Redis database indexes and/or explicit prefixes. Sharing one database is fine only if prefixes differ — the danger is that a cache flush wipes sessions or queued jobs.

// config.php (verify exact key names against the package README for your version)
'cache' => [
    'driver' => 'redis',
    'prefix' => 'flarum:cache:',
],
'session' => [
    'driver' => 'redis',
    'prefix' => 'flarum:session:',
],
'queue' => [
    'driver' => 'redis',
    'queue' => 'default',
    'retry_after' => 120,
],

Drive config from the environment. Flarum's config.php is plain PHP with no env() helper, so use getenv() / $_ENV:

'host' => getenv('REDIS_HOST') ?: '127.0.0.1',

Run the queue worker under a supervisor, as the web user, with the same PHP binary:

php flarum queue:work --sleep=3 --tries=3

Use queue:listen in development so code changes are picked up without restarting the worker. In production, treat it like Laravel: long-running queue:work processes must be restarted on deploy.

Deploy hook pattern:

php flarum cache:clear
php flarum queue:restart   # or restart supervisor

Cache usage inside extensions mirrors Laravel: resolve the cache repository from the container and use remember/put/forget with explicit TTLs. Redis will not evict keys for you unless you set maxmemory-policy, so don't rely on implicit expiry.

Multiple Redis servers are handled the same way as Laravel: define named connections and reference the connection name from each driver config. This is the clean way to put the queue on a different Redis instance from the cache.

Observation while rolling out: redis-cli MONITOR for correctness, INFO stats for hit rate, and LLEN on the queue key to watch backlog. That combination covers 90% of day-to-day operational questions.

Gotchas and Tips

• Silent no-op if not enabled. The drivers are registered by the package's service provider through Flarum's extension loader. If the extension is disabled, your 'driver' => 'redis' config is at best ignored and at worst throws a driver-not-found error on boot. Enable it before debugging config.
• Client mismatch. Setting 'client' => 'phpredis' without ext-redis installed fails at bootstrap. Either install the extension or set 'client' => 'predis' and require predis/predis.
• Upstream drift. This is a 14-star package tracking Flarum core; Flarum has historically shipped or absorbed Redis support. Pin the version in composer.json, read the small src/ directory before upgrading, and check Flarum release notes — it can become redundant or require a major bump.
• cache:clear semantics with prefixes. Without a prefix, a flush can hit the whole database and take sessions and queued jobs with it. With a prefix, Illuminate's Redis store flushes only prefixed keys via an eval script. Always set a prefix or isolate databases.
• Session eviction looks like random logouts. If you set maxmemory-policy to an eviction policy on a database holding sessions, users get logged out unpredictably. Use a dedicated database and noeviction or a generous limit for sessions.
• retry_after versus job runtime. retry_after must exceed the longest-running job, or Redis will hand the job to a second worker while the first is still running, causing duplicate work. Also ensure the failed_jobs table exists (run migrations), or failures are lost.
• Worker user and permissions. Run queue:work as the same user as PHP-FPM, with write access to storage/. Smoke-test with --once before wiring into supervisor.
• Timeouts stall the whole forum. phpredis defaults can make a slow Redis block every request. Configure timeout and read_write_timeout, and consider persistent connections.
• Cluster limits. Multi-key operations (cache tags, eval-based flush) don't work cleanly on Redis Cluster. If you're on cluster, avoid tags and verify the package passes connection options through in your version.
• Debugging order: redis-cli PING → MONITOR during a page load → confirm config.php actually contains the block → php flarum info for the enabled extension → PHP error log for "driver not supported" exceptions.
• Extension points are intentionally thin. This is a driver package, not a framework. If you need custom serialization, metrics, or failover logic, wrap the cache repository in your own service provider rather than forking; keep the fork surface as small as possible so upstream updates stay cheap.