Filament Queue Monitor Laravel Package

Getting Started

This package gives you a UI plus a small set of endpoints for browsing, retrying, and deleting rows from Laravel's failed_jobs table. It is still pre-1.0 (v0.1.1), so expect the public surface to shift between minor versions.

1. Install it with Composer and publish whatever assets/config it ships:

   composer require <vendor>/<package>
   php artisan vendor:publish --tag=<package>-config   # check the provider for exact tags
   

2. Look at the config file first. The only knob evidenced by the changelog is list_limit, which caps how many failed jobs the list page loads. Set it to something sane (25–100) before you point the list at a production database.

3. Confirm your queue failure driver matches the package's expectations:

   // config/queue.php
   'failed' => [
       'driver' => env('QUEUE_FAILED_DRIVER', 'database-uuids'),
       'database' => env('DB_CONNECTION', 'mysql'),
       'table' => 'failed_jobs',
   ],
   

   On Laravel 12 the default is database-uuids, meaning rows are keyed by uuid. The package resolves records by that key. If you have a legacy install that still writes numeric IDs (or you switched drivers mid-life), the list will render but every action will 404 — that mismatch is exactly the bug fixed in v0.1.1.

4. First use case: break something on purpose. Dispatch a job that throws, run the worker once, then open the package's failed-jobs route and retry it. If retry works end-to-end you have the wiring correct.

Implementation Patterns

Version-aware keying. The single most important thing to get right is how records are identified. Under database-uuids the identifier is the uuid column; the list must link and act on that value. If you are on Laravel 12 and still seeing 404s after upgrading to v0.1.1, your failed.driver is not what you think it is — dump config('queue.failed.driver') in tinker rather than trusting .env (config caching is the usual culprit).

Let the database do the limiting. Before v0.1.1, Laravel 10/11 installs loaded the entire failed_jobs table and sliced in PHP. On anything with real failure volume that is a memory and latency problem. After the fix, list_limit is applied in SQL. Keep the limit in config rather than hardcoding, and be aware that the count/pagination semantics may differ slightly from the old in-memory behaviour — verify your pagination shows the total you expect.

Wrap retry/delete in your own tooling when you need audit. The package's retry and delete actions are thin wrappers over queue:retry and queue:flush-style operations. If you need "who retried what, when", intercept at the job level (a JobRetrying/JobFailed listener, or an Auditable trait on your jobs) rather than trying to hook the UI.

Scheduled hygiene alongside the UI. The list is a diagnostic surface, not a retention policy. Pair it with a scheduled prune so the table does not grow unbounded:

// routes/console.php
Schedule::command('queue:prune-failed --hours=168')->daily();

Test the failure path, not just the happy path. In feature tests, insert a row directly into failed_jobs with a matching uuid (generate via (string) Str::uuid()), then hit the package's routes and assert the retry/delete redirects. This catches driver/key mismatches without needing a real queue worker.

Gate the routes. These endpoints mutate queue state. If the package does not ship its own authorization, put it behind your admin middleware — a failed-jobs panel is effectively a "replay arbitrary production jobs" button.

Gotchas and Tips

• 404 on every action is a key-type bug, not a routing bug. The database-uuids failer looks rows up by uuid; if the list links by id you get a 404 that looks like a missing route. Fixed in v0.1.1 for Laravel 12 — if you are pinned to 0.1.0, upgrade.
• list_limit behaviour changed on Laravel 10/11. It now applies in the query. If you had previously "worked around" the in-memory slicing (e.g. by relying on the full table being present for client-side search or a total count), re-check that screen after upgrading.
• Failer driver migrations are one-way in practice. Switching QUEUE_FAILED_DRIVER from database to database-uuids leaves old numeric-ID rows orphaned — they will appear in the list but cannot be resolved. Clear or migrate them deliberately.
• Config cache. Any change to queue.failed.* or the package's list_limit needs php artisan config:clear in local dev and a fresh deploy in production. Most "the fix didn't work" reports are stale config caches.
• Add an index if you query beyond the default. The default failed_jobs migration indexes uuid and the failed_at/queue columns; if you add filtering or sorting in your own extensions, verify with EXPLAIN that you are not full-scanning.
• Pre-1.0 churn. At 0.1.x, a minor bump can contain behaviour changes. Pin the version in composer.json and read the release notes before bumping — v0.1.1 itself is a pure bug-fix release with no breaking changes and no deprecations, so it is safe to take.
• Debugging checklist when an action silently does nothing: confirm the row's uuid is non-null, confirm config('queue.failed.driver'), confirm the record actually exists in the connection the package reads from (a multi-connection app can have the package pointed at the wrong DB), then check the response status in the network tab — the v0.1.1 bug manifested as a 404, not a 500.
• Extension point: the config file is the safest place to customise. Avoid patching vendor views for anything you might want to keep, since view paths are the most likely thing to move in a 0.x release.