Filament Queue Management Laravel Package

Getting Started

• Install with composer require for the package, then publish its assets and config: php artisan vendor:publish --tag=<package>-config (and --tag=<package>-migrations if it ships its own). Run php artisan migrate — the package reads from Laravel's core job_batches table, so if you already use Bus::batch() you will have data immediately.
• Look first at config/<package>.php. The two keys that matter on day one are the dashboard route/prefix and the authorization gate. Wire the gate into AuthServiceProvider (or the package's viewX callback) before you deploy anything — a batch view leaks job payloads, exception messages, and queue names.
• First use case: open the batch list, find a finished_at-set batch with pending_jobs > 0, and drill into it. You want the failed job UUIDs and the options blob (the serialized batch then/catch/name/allowFailures payload) to answer "why did this chain stop?" without shelling into the DB.

Implementation Patterns

• Name your batches. Bus::batch([...])->name('nightly-export')->dispatch() is the single highest-leverage habit: an unnamed batch is id-only in the UI and unusable for support triage. Names are stored in the options blob, which this view now decodes, so names are visible where they matter.
• Use allowFailures() deliberately. On a batch that tolerates failures, the view showing non-empty failed_job_ids is expected noise, not an incident. On a strict batch, any entry there means the catch callback fired and the remaining jobs were discarded — check the cancelled_at column to distinguish "cancelled by failure" from "cancelled by code".
• Cross-reference the failed job list, not the batch. failed_job_ids holds UUIDs pointing at failed_jobs.uuid, not integer ids. Pattern: copy the JSON array from the batch view, then php artisan queue:retry <uuid> <uuid> — batches have no batch-level retry, so recovery is always per-job.
• Keep the viewer in the ops loop, not the code path. Register the route behind your existing admin middleware and treat it as read-only observability alongside Horizon/Telescope. Don't call into the package from application code; dispatch batches, then inspect.
• Instrument the callbacks. Because options is now readable, it's worth putting structured payloads in there — e.g. ->name(json_encode(['tenant' => $id, 'kind' => 'export'])) — and the UI will render it as inspectable JSON rather than an opaque string. Keep it small; it's a text column.
• Staging parity for driver differences. If you develop on SQLite/MySQL and deploy on PostgreSQL, exercise the batch view on the Postgres environment specifically before trusting it — the column encoding differs (see Gotchas).

Gotchas and Tips

• PostgreSQL options encoding. Laravel's database batch repository stores options in a driver-dependent form; on Postgres the value can come back base64-encoded. Version 1.1.2 of this package detects and decodes that, so the UI is correct — but any ad-hoc SQL you write (select options from job_batches where id = ...) still gets the raw encoded string. Always decode before unserialize/json_decode in your own scripts.
• failed_job_ids display changed in 1.1.2 — from comma-joined to a JSON list. Anything that scraped or copy-pasted the old format (runbooks, Slack templates, screenshots in your incident docs) needs updating to expect ["uuid","uuid"].
• Pruning is your problem. job_batches grows unbounded. php artisan queue:prune-batches --hours=168 keeps it sane, but note the default retention also drops successful batches — if you use this view for audit/compliance, prune only finished-and-uninteresting batches or set a longer window.
• finished_at null is not "stuck". A batch stays open while any job is pending; jobs lost to a crashed worker leave the batch permanently un-finished with pending_jobs > 0 and empty failed_job_ids. That signature (no failures, never finishes) is your cue to look at worker timeouts, not at the batch.
• Very large batches render poorly. Thousands of IDs in a single JSON blob is a lot for one request; paginate or filter at the DB level for batches above a few hundred jobs rather than relying on the view.
• Route exposure is the real risk. The gate defaults are easy to overlook in a fresh install; verify with a logged-out request to the dashboard path in staging before it reaches production, and check it's not picked up by any catch-all Route::fallback.
• Extension point: if you need a different rendering (CSV export, Slack digest of failed batches), the decoding logic in 1.1.2 is the piece to reuse rather than re-derive — wrap it once in your own helper so a future driver change only breaks one place.