Nova Queue Management Laravel Package

Getting Started

1. Install the package via Composer.

composer require kaiserkiwi/nova-queue-management

This is a pure Nova tool — no migrations, no schema changes, no config file to publish for basic use. If assets are not auto-published, run the standard Nova asset publish step (php artisan nova:publish).

2. Register the tool in app/Providers/NovaServiceProvider.php.

use KaiserKiwi\NovaQueueManagement\QueueManagement; // confirm FQCN from the package README

public function tools()
{
    return [
        QueueManagement::make(),
    ];
}

The fork descends from den1n/nova-queue-management; if you're upgrading from the abandoned package, the namespace may still be Den1n\NovaQueueManagement. Verify against the package's composer.json autoload block before wiring it in.

3. Look here first after registering:

• The Nova sidebar — the tool registers a menu entry; if it doesn't appear, your tools() array isn't being read (clear config/cache) or the tool's canSee is failing.
• vendor/kaiserkiwi/nova-queue-management/src/ — the tool class, the routes it registers, and the Vue components live here. That's where authorization hooks and route middleware will be added if you need them.
• The jobs and failed_jobs tables — that's the actual data surface the tool reads and mutates.

4. Your first use case: failed-job triage.

Push a job that throws:

dispatch(function () {
    throw new RuntimeException('test failure');
})->onQueue('default');

Run your worker so the job fails and lands in failed_jobs. Then open Nova → Queue Management → Failed Jobs, click the row, and inspect the exception and serialized payload. Retry it from the UI. That single loop — read exception, read payload, retry or delete — is the entire value proposition; verify it end-to-end in staging before trusting it during a real incident.

Implementation Patterns

Register the tool like any Nova tool, but gate it deliberately. The default registration exposes queue state and destructive actions (retry, delete, flush) to everyone who can log into Nova. Wrap it in whatever authorization primitive your Nova setup uses:

public function tools()
{
    return [
        QueueManagement::make()
            ->canSee(fn ($request) => $request->user()?->hasRole('ops')),
    ];
}

For most teams the real gate belongs in a policy or a Nova gate in NovaServiceProvider::gate(), since the tool's internal routes should also be protected, not just the menu entry. Treat "can see the menu item" and "can hit the POST routes" as two separate checks and verify both.

Pair it with failed-job pruning from day one. The tool is an operator view over failed_jobs; it does not solve retention. Schedule Laravel's built-in pruning so the table the UI reads stays bounded:

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

Without this, a noisy week (or a real incident) turns the failed-jobs view and the bulk-retry action into slow synchronous requests at the exact moment you need them.

Use it as the shared operator surface, and drive bulk work deliberately. The natural workflow split:

• Individual triage — read the exception and payload, retry or delete one job. This is the safe, high-value path.
• Bulk flush — reserve for cases where the failure is systemic and the queue's contents are known-bad (e.g. a bad deploy that corrupted payloads). Treat flush as a runbook action, not a button to click when it's slow.

Integrate it as the console-adjacent replacement for SSH. For teams on database or SQS drivers, this replaces the "SSH in, run php artisan queue:failed, find the ID, run queue:retry <id>" loop. Document the exact navigation path (Nova → Queue Management → Failed Jobs) in the on-call runbook and link it from your alerting payloads so a paged engineer lands on the right screen.

For Redis + Horizon shops, don't double up. Horizon already covers inspection and retry for Redis queues. Adopt this tool only if the explicit goal is consolidating operator actions inside Nova. Otherwise it's redundant UI on the same data.

Extension points. If you need audit attribution (who retried what), don't monkey-patch the package — wrap it. Either subclass the tool and override the action routes with your own versions, or listen to Laravel's queue events (JobRetryRequested, JobFailed) and log the Nova-authenticated user from a middleware on the tool's routes. Attribution is not shipped out of the box; assume you have to build it.

Gotchas and Tips

The license is NOASSERTION. GitHub could not classify it, which means legal/compliance cannot assume OSI terms. For a privileged, production-adjacent admin surface, resolve this before it lands in composer.json on a commercial Nova install. This is a procurement gate, not a footnote.

Constraint-widening ≠ verified compatibility. Release 1.4.0 (2025-01-20) widened the laravel/nova constraint to admit Nova 5. Read composer.json directly to confirm it's a disjunction (^4.0|^5.0) rather than a hard replacement of Nova 4 — that single fact decides whether the package is a bridge or a forced cutover. Then confirm the Nova 5 path actually boots: there's no CI evidence it was exercised, so bake it in staging and click through registration, asset loading, and the failed-jobs routes before standardizing.

Single maintainer, no dependents, no SLA. Best-effort GitHub issues with unbounded escalation latency. Pin the exact version in composer.json, keep the previous version noted as a rollback target, and name an owning engineer. Don't let this dependency sit unowned.

Bulk retry and flush are synchronous web requests against failed_jobs. At high row counts — precisely when you need them — they can time out or contend. Test at representative volume (a seeded failed_jobs table with the row counts you actually see) before relying on the flush button during an incident. If you blow the timeout, you may have partially flushed with no clear completion signal.

Destructive actions on production data. Retry, delete, and flush act on real queue tables. A misconfigured or absent authorization gate causes data loss, not a degraded page. This is the highest-severity, lowest-visibility risk in the whole adoption; treat the gate as a required step, not a nice-to-have, and require a second pair of eyes for flush during incidents.

"Works with any queue driver" means it reads jobs/failed_jobs, not that it manages every driver's internals. SQS and Redis still surface failures through Laravel's failed_jobs table, so the failed-jobs view works — but "pending jobs" reads the jobs table, which is only authoritative for the database driver. Don't assume a Redis or SQS queue's in-flight jobs are visible just because the tool installed cleanly.

Payload display is a serialized job blob. Laravel serializes the command class and its properties; large payloads are truncated or hard to read in a narrow Nova detail view. For complex failures, copy the payload into tinker and unserialize() it to inspect the actual job object — the Nova view is for the exception and a quick sanity check, not deep debugging.

Tool not appearing in the sidebar? In order: (1) confirm the FQCN matches the package's autoload namespace (the den1n → kaiserkiwi fork may or may not have renamed it); (2) php artisan config:clear and nova:publish; (3) confirm your canSee/gate isn't returning false; (4) check the browser console — a failed asset load in the Nova tool's Vue entry will render an empty panel rather than an error.

Orthogonal to Horizon — say so plainly during evaluation. They don't conflict, and this package does not replace Horizon's metrics, wait-time telemetry, or autoscaling. It's an operator UI over queue tables. If your roadmap needs job-chaining visualization, multi-tenant queue isolation, or audit-grade action attribution, this package clarifies what you're not getting and where a dedicated platform spend belongs.