Flarum Horizon Laravel Package

Getting Started

This extension surfaces the Laravel Horizon dashboard inside Flarum's admin panel, so you can watch queues, failed jobs and Redis stats without SSHing into the host or exposing Horizon's own HTTP routes.

Minimal setup:

1. composer require blomstra/flarum-ext-horizon in the Flarum root (the same place Horizon itself is installed).
2. php flarum extension:enable blomstra-horizon.
3. Confirm Horizon is actually configured and running for queues — the extension is a window, not a worker. You still need php flarum horizon (or artisan horizon) under supervisor/systemd, plus the usual config/horizon.php.
4. Log into /admin and open the Horizon tab. First use case: watch a batch job (e.g. mass notification, reindexing) progress in real time and inspect failures in the "Failed Jobs" tab rather than tailing logs.

If the dashboard renders but is empty, the problem is almost always Horizon/queue config, not the extension.

Implementation Patterns

• Supervised Horizon, not queue:work. Run php flarum horizon under supervisor with numprocs and balancing per environment; the dashboard's metrics only make sense when Horizon owns the workers.
• Separate queue connections by workload. Use Horizon's environments.<env>.supervisor-* blocks to isolate slow jobs (emails, exports) from fast ones; the dashboard's per-queue view is the quickest way to spot a starved queue.
• Retry/failed-job triage loop. Use the failed-jobs tab as your first stop when users report "no email arrived" — retry in place, then php flarum horizon:clear / horizon:forget in scripts or scheduled tasks rather than clicking through hundreds of entries.
• Redis admin widget for capacity questions. As of 0.4.3 the widget also shows the eviction policy — check this whenever queue throughput drops "for no reason"; allkeys-lru under memory pressure is a classic cause of disappearing jobs.
• Metrics-driven autoscaling. Feed Horizon's throughput/wait-time metrics into your monitoring (or scrape the /horizon/api/* endpoints behind a protected route) so alerts fire before queues back up.
• Access control. Keep the extension enabled only for trusted admins; it exposes job payloads and config. Pair with Flarum's admin permissions rather than relying on route obscurity.

Gotchas and Tips

• Max memory was misreported before 0.4.3. If you tuned memory_limit in Horizon based on the dashboard showing auto, re-check on 0.4.3 — the displayed value now reflects reality and your assumptions may have been wrong.
• Eviction policy is the new signal. The Redis widget now shows the eviction policy; set it explicitly (noeviction for dedicated queue Redis, or volatile-lru only if you accept losing jobs) and verify it in the UI instead of guessing from redis-cli CONFIG GET.
• Extension ≠ Horizon install. Enabling the extension does not install Horizon, publish its config, or start workers. Missing vendor/bin/horizon or a stale config/horizon.php produces a blank dashboard with no error in the Flarum log.
• Redis connection mismatch. Horizon uses its own use connection setting; if Flarum queues go to default but Horizon watches horizon, you'll see nothing.
• Metrics retention. Horizon's trim settings silently drop old job data — raise trim.recent/trim.completed if you need historical forensics.
• Failed-job table growth. Prune with horizon:clear in a scheduled command; the admin UI is not a substitute for retention policy.
• Versioning. Pin 0.4.3 if you depend on accurate memory/eviction reporting; earlier 0.4.x lines display misleading Redis figures.