Rocketeers Laravel Laravel Package

Getting Started

• Install/update the package as usual with Composer. If you are on Laravel 13, this release allows orchestra/testbench 11.x so the test suite can actually boot Laravel 13.29; runtime support was already declared, but now it is exercised.
• Set ROCKETEERS_HORIZON_SECRET in each environment. Rocketeers writes this automatically when provisioning; for an existing environment use Insert › Horizon monitoring in the Rocketeers env editor.
• Optionally set ROCKETEERS_HORIZON_ORIGIN if the dashboard is served from a different origin, and ROCKETEERS_HORIZON_TTL if 300 seconds is not suitable.
• Make sure laravel/horizon is installed in any environment where you expect the stats endpoint to work. Without Horizon the endpoint returns 404, which is intentional and safe.
• First use case: let the Rocketeers dashboard generate the signed URL server-side and poll GET /rocketeers/horizon/stats?expires=<ts>&signature=<hmac> from the browser. To verify locally, generate a signed URL from your application code or the package helper, then curl it; do not paste the secret into browser code.
• Look first at the package config/route registration and the Rocketeers env editor. Check php artisan route:list | grep rocketeers to confirm the route is registered in the target environment.

Implementation Patterns

• Browser dashboard polling: Generate the signed URL on the server, hand only the short-lived URL to the frontend, and refresh it before expires passes. Treat the URL as sensitive for its TTL but never ship ROCKETEERS_HORIZON_SECRET to the browser.
• Server-to-server monitoring: Use the bearer-token access added in 2.9.0 for backend jobs or scripts that need Horizon stats. Use the signed URL for browser dashboards. The two mechanisms are independent and can coexist; choose based on whether the caller is a browser or a trusted server.
• Custom monitors/alerts: Poll the endpoint from your own backend or scheduled job and alert on aggregate values such as failedJobs, wait, or jobsPerMinute. Keep signatures short-lived and generate them per request or cache them for slightly less than the TTL.
• Testing: Add feature tests for the three important cases: valid signature returns 200, invalid/expired signature returns 403, and missing Horizon returns 404. Use time travel to verify expiry and assert that an empty secret keeps the endpoint closed.
• Deployment/config: Keep the secret environment-specific. If you rotate it in Rocketeers, expect previously signed URLs to fail immediately; that is usually desirable for a short-lived dashboard URL.
• CORS-friendly integration: The endpoint has no custom request headers, so browser calls stay CORS “simple” requests and do not preflight. Keep it that way; do not add Authorization or other custom headers to browser polling if you want to preserve that behavior.

Gotchas and Tips

• An empty ROCKETEERS_HORIZON_SECRET keeps the endpoint closed. If the dashboard gets 403, check that the secret is actually present in the deployed environment, not just locally.
• Invalid and expired signatures both return 403. Check expires first, then the secret, then whether the signature was generated for the exact URL/query string.
• The route is registered outside the web middleware group: there is no session, cookie, or CSRF token involved. Do not wrap it in session/auth middleware and expect normal browser auth behavior.
• A 404 usually means Horizon is not installed in that environment. That is a safety behavior, not necessarily a broken deployment.
• The endpoint is deliberately narrow: aggregate counts only, no job payloads, no Horizon action endpoints. Do not try to use it to retry, delete, or inspect individual jobs.
• If ROCKETEERS_HORIZON_ORIGIN is set, make sure it matches the dashboard origin exactly. If it is wrong, browser calls can fail even though the signature is valid.
• Clock skew can expire URLs earlier than expected. Keep TTLs short but leave a small refresh buffer in the frontend.
• After changing env values, run php artisan config:clear (or rebuild config cache) before debugging further.
• The secret is described as your Rocketeers environment id and is used as the signing secret. Treat it like any other secret: do not log it, expose it in frontend assets, or commit it to source control.
• If you are upgrading for Laravel 13, the meaningful change is test-suite coverage via orchestra/testbench 11.x. Run your package tests on Laravel 13 to catch framework-level regressions, and keep an eye on any testbench-related dev dependency constraints.