PHPackages gwhitdev/laravel-queue-doctor - 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. gwhitdev/laravel-queue-doctor ActiveLibrary[Caching](/categories/caching) gwhitdev/laravel-queue-doctor ============================= Diagnose Laravel queue health and web-tier store reachability: catch worker/connection mismatches, stalled backlogs, and the cache/session Redis outages that 500 every request. v1.0.0(today)00MITPHPPHP ^8.2CI failing Since Jun 18Pushed todayCompare [ Source](https://github.com/gwhitdev/laravel-queue-doctor)[ Packagist](https://packagist.org/packages/gwhitdev/laravel-queue-doctor)[ RSS](/packages/gwhitdev-laravel-queue-doctor/feed)WikiDiscussions main Synced today READMEChangelog (1)Dependencies (4)Versions (2)Used By (0) Laravel Queue Doctor ==================== [](#laravel-queue-doctor) A single Artisan command — `php artisan queue:doctor` — that catches the three queue/infra failure modes Laravel itself stays quiet about: 1. **Worker/connection mismatch** — jobs dispatch to one connection (say `redis`) but the only running worker drains another (say `database`). Jobs pile up forever and *nothing errors*. They just never run. 2. **Stalled backlog** — a connection has old pending jobs and no worker is draining them (dead worker, wrong supervisor config, scaled-to-zero). 3. **Web-tier store outage** — your cache or session backend (often Redis) is unreachable. This is the nastiest one: it `500`s **every single request** through `StartSession`/the cache repository, long before any *queue* symptom appears — and a queue health check that only looks at the queue is blind to it. Why this exists --------------- [](#why-this-exists) This was extracted from a production Laravel app after a multi-hour outage with a frustratingly simple root cause: jobs were dispatched to Redis, but the worker was started as `queue:work database`. No exception, no failed job, no log line — work simply vanished into a queue nobody was draining. A second incident came from the *other* direction: Redis (backing both session and cache) dropped its connection, and `StartSession` turned every route into a `500` while the queue looked perfectly healthy. `queue:doctor` is the check we wished we'd had: it asserts the connection you *dispatch* to is the one a worker is actually *draining*, and it round-trips the cache/session backends every request depends on. Installation ------------ [](#installation) ``` composer require garethwhitleychard/laravel-queue-doctor ``` The service provider is auto-discovered. No config or migration to publish. Usage ----- [](#usage) ``` php artisan queue:doctor ``` Example output: ``` Default connection: redis (driver: redis) Failed jobs: 0 +----------------------+----------+---------+------------+ | Connection | Driver | Pending | Oldest job | +----------------------+----------+---------+------------+ | redis (default) | redis | 0 | — | | database | database | 0 | — | +----------------------+----------+---------+------------+ Workers draining: redis +----------------+----------------+--------+---------------+ | Web-tier store | Backend | Status | Detail | +----------------+----------------+--------+---------------+ | cache | redis (redis) | ok | round-trip ok | | session | redis (default)| ok | reachable | +----------------+----------------+--------+---------------+ Queue healthy: default connection 'redis' has no backlog. ``` ### Options [](#options) OptionDefaultDescription`--max-age``3600`Age in seconds above which a backlog on the **default** connection is treated as a hard failure rather than a transient warning.### Exit codes [](#exit-codes) `queue:doctor` exits **non-zero** on a mismatch, a stalled backlog, or an unreachable web-tier store — so it drops straight into CI, a deploy gate, or a cron-driven healthcheck: ``` # fail a deploy / alert if the queue or its backing stores are unhealthy php artisan queue:doctor || notify-oncall "queue:doctor failed" ``` How the worker detection works ------------------------------ [](#how-the-worker-detection-works) Worker discovery parses the process list (`ps -eo args`) for `queue:work`/`queue:listen` and reads the connection argument. It is **best-effort**: in environments where the process list isn't visible (some containers, restricted hosts) it reports "could not inspect process list" and skips the mismatch verdict rather than producing a false alarm. The backlog and store checks still run. Failing over a downed store --------------------------- [](#failing-over-a-downed-store) When `queue:doctor` reports `WEB-TIER STORE DOWN`, the fastest recovery that keeps the app serving is to move off the broken backend until it recovers: ``` CACHE_STORE=database SESSION_DRIVER=cookie ``` Testing ------- [](#testing) ``` composer install vendor/bin/pest ``` License ------- [](#license) MIT. See [LICENSE](LICENSE). ### Health Score 39 — LowBetter than 85% of packages Maintenance100 Actively maintained with recent releases Popularity0 Limited adoption so far Community6 Small or concentrated contributor base Maturity45 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% 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 Unknown Total 1 Last Release 0d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/16516615?v=4)[Gareth Whitley](/maintainers/gwhitdev)[@gwhitdev](https://github.com/gwhitdev) --- Top Contributors [![gwhitdev](https://avatars.githubusercontent.com/u/16516615?v=4)](https://github.com/gwhitdev "gwhitdev (2 commits)") --- Tags laravelartisanredisqueuehorizondiagnosticshealth checkops ### Code Quality TestsPest ### Embed Badge ![Health badge](/badges/gwhitdev-laravel-queue-doctor/health.svg) ``` [![Health](https://phpackages.com/badges/gwhitdev-laravel-queue-doctor/health.svg)](https://phpackages.com/packages/gwhitdev-laravel-queue-doctor) ``` ### Alternatives [spatie/laravel-responsecache Speed up a Laravel application by caching the entire response 2.8k8.7M64](/packages/spatie-laravel-responsecache)[laravel/ai The official AI SDK for Laravel. 9782.1M157](/packages/laravel-ai)[spatie/laravel-health Monitor the health of a Laravel application 87411.3M152](/packages/spatie-laravel-health)[yangusik/laravel-balanced-queue Laravel queue management with load balancing between partitions (user groups) 8512.6k](/packages/yangusik-laravel-balanced-queue)[iazaran/smart-cache Smart Cache is a caching optimization package designed to enhance the way your Laravel application handles data caching. It intelligently manages large data sets by compressing, chunking, or applying other optimization strategies to keep your application performant and efficient. 2119.7k](/packages/iazaran-smart-cache) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)