Laravel Belvedere Laravel Package

Getting Started

Belvedere is a first-release, Horizon-style dashboard for Laravel's database queue driver. If you already use QUEUE_CONNECTION=database, this is intended to give you the visibility Horizon provides for Redis queues: pending jobs, failures, throughput, and per-queue activity.

Minimal setup:

1. Require the package:

   composer require <vendor>/belvedere
   

2. Publish any package assets/config if the README instructs it:

   php artisan vendor:publish --tag=belvedere-config
   

3. Confirm the dashboard route and authorization gate in the published config before exposing it outside local development.
4. Ensure your app is actually using the database queue driver:

   QUEUE_CONNECTION=database
   

5. Start a worker as usual:

   php artisan queue:work
   

6. Visit the dashboard route locally and inspect the jobs / failed_jobs tables through the UI.

Where to look first:

• CHANGELOG.md for v0.1.0 scope and known limitations.
• The package config file for route prefix, middleware, and authorization gate.
• The dashboard's failed-jobs view, since retrying and inspecting failed payloads is the most immediately useful day-to-day workflow.

First use case: replace ad-hoc SQL queries against jobs and failed_jobs with a dashboard view when debugging a stuck or failing database queue.

Implementation Patterns

Use it as an operational view, not a replacement for workers. Belvedere observes the database queue; it does not process jobs. Keep queue:work supervised by Supervisor/systemd exactly as before.

Local development debugging. Point the dashboard at your local database queue and use it to answer:

• Which queue has a backlog?
• Which job class is failing repeatedly?
• What exception and payload are attached to a failed job?
• Is a retry actually re-entering the queue?

Staging/production visibility. Put the dashboard behind your existing auth middleware or the package's authorization gate. A common pattern is to allow only users with an admin flag, or to restrict access by environment:

// config/belvedere.php or route middleware config
'middleware' => ['web', 'auth', 'can:viewBelvedere'],

Pair with Laravel's native queue commands. Keep using:

php artisan queue:work --queue=high,default
php artisan queue:retry all
php artisan queue:flush

Belvedere is most useful as the read/inspect layer on top of those commands.

Use queue names intentionally. If you split workloads across high, default, and low, make sure workers and the dashboard are aligned on queue names. A dashboard showing one queue while workers consume another is a common source of false confidence.

Database-specific verification. The release notes call out MySQL 8.4/9.7, MariaDB 11.8, PostgreSQL 17, and SQLite, plus Laravel 12 and 13. If you are on an older Laravel or database version, test the dashboard in a non-production environment before relying on it.

Integration with failed-job triage. A practical workflow:

1. Filter to failed jobs.
2. Inspect the exception and payload.
3. Fix the underlying issue.
4. Retry the job from the dashboard or CLI.
5. Confirm it leaves the failed state and is picked up by a worker.

Gotchas and Tips

v0.1.0 means early-stage API. Pin the version in composer.json and review the CHANGELOG before upgrading. Config keys, routes, and UI behavior may change in minor releases while the package is pre-1.0.

The dashboard is only as good as the queue tables. Large jobs and failed_jobs tables can make any database-backed dashboard slow. Keep an eye on indexes and retention. If your failed jobs table grows indefinitely, prune it deliberately rather than letting the dashboard query an ever-growing dataset.

Do not expose it publicly. A queue dashboard can reveal job payloads, exception traces, and application internals. Treat it like Telescope or Horizon: local by default, authenticated everywhere else.

It does not replace queue:work. A common first-run mistake is assuming the dashboard starts or supervises workers. It does not. No worker means no processing, regardless of what the UI shows.

SQLite behaves differently under concurrency. SQLite is listed as supported, but database queue workloads with multiple workers can hit locking behavior that MySQL/PostgreSQL users will not see. Use SQLite support for local development and small workloads; validate carefully before production use.

Config caching can hide changes. After editing the package config or authorization gate, run:

php artisan config:clear

or rebuild the config cache in deployments.

Check route registration and middleware first when the dashboard 404s or 403s. Most setup issues are route prefix, middleware, or authorization gate configuration rather than the package itself.

Extension points to inspect: published config, route middleware, authorization gate, and any published views/assets. Prefer configuring those over editing vendor files.

Test against your actual database version. The release notes list specific tested versions. If you are on an older MySQL/MariaDB/PostgreSQL release, smoke-test the dashboard's queries in staging before depending on it for incident response.