Laravel Horizon Restart Laravel Package

Technical Evaluation

What this package is. huangdijia/laravel-horizon-restart is a small utility package that exposes Laravel Horizon's worker-restart capability (horizon:terminate / horizon:restart) through an application-facing surface (route/command), so operators can recycle queue workers without SSH access to each host. It is a convenience layer, not infrastructure — Horizon itself remains the runtime, and the package is a thin wrapper over a first-party Artisan signature.

What v3.1.0 changes. v3.1.0 is a pure compatibility release: Laravel 12.x support (via Laravel Shift) and PHP 8.4 support. Minor version bump, no breaking changes, no new features, no deprecations, no configuration or API surface changes announced. The only material signal is that the package has been validated against the current Laravel major and the current PHP minor, and that a second contributor (Laravel Shift automated tooling) has touched the repo.

Architecture fit. Good architectural fit if the estate is already on Horizon. It does not introduce a new persistence layer, queue driver, or daemon — it is a control-plane button. If the estate is not on Horizon (e.g., database queue + queue:work under Supervisor), this package is irrelevant. Fit is therefore conditional on an existing Horizon commitment.

Integration feasibility. High. Standard Composer install with Laravel package auto-discovery; typical integration is composer require, publish config, and gate the route behind auth/middleware. No database migrations, no schema, no long-running process to manage.

Technical risk (ranked).

1. Exposure of a privileged control endpoint (highest). A restart endpoint that is unauthenticated or under-authenticated is a denial-of-service primitive against queue throughput. Must be gated by middleware, IP allowlist, and/or signed token, plus rate limiting.
2. Blast radius of the restart itself. Terminating Horizon interrupts in-flight job processing; jobs mid-execution can be lost or retried depending on tries/timeout/retry_after and idempotency. This is a data-correctness risk owned by the application, not the package — but the package makes the action one click away, which increases frequency.
3. Single-maintainer supply chain. Small repo, one primary maintainer, low commit volume. Low code surface limits exploitability, but maintenance continuity is a real procurement concern for a production control path.
4. Multi-node semantics. Horizon runs per-host; a single HTTP call reaches one node unless the request fans out. Operators may believe "restart" restarted the fleet when it restarted one supervisor.
5. Observability gap. Little assurance of audit trail, structured logging, or metrics around who triggered a restart and what happened after.

Key questions for the maintainer / internal owners.

• Does v3.1.0 ship a route, an Artisan command, or both — and is the route registered by default or opt-in?
• What are the exact composer.json constraints for laravel/framework, php, and laravel/horizon? Is Horizon 5.x required?
• What authentication/authorization primitives exist out of the box (gate, token, signed URL), and are they secure-by-default or documentation-dependent?
• Does a single invocation restart all supervisors on a multi-node deployment, or only the local node?
• Test coverage and CI matrix for the new Laravel 12 / PHP 8.4 targets?
• Is there an audit log hook or event fired on restart?

Verdict: low technical risk as code, medium operational risk as a control plane. Approve for evaluation in a non-production environment; production adoption should be conditional on authentication review and audit logging.

Integration Approach

Stack fit. Targets Laravel applications running Horizon on Redis. v3.1.0 explicitly aligns with Laravel 12.x and PHP 8.4, so it fits an estate that is current or moving current. It also remains usable on the prior majors (v3.0.0 was the Laravel 11-era line), giving a clean bridge across the upgrade window.

Compatibility and migration path.

• From v3.0.0 → v3.1.0: drop-in, no migration steps. Semver minor plus zero "Changed/Breaking" entries in the release notes. Update the constraint, run the test suite, deploy.
• From v2.x → v3.x: this happened at the prior release, not here. Treat as a separate work item; do not bundle it with the v3.1.0 bump.
• Constraint hygiene: pin to ^3.1 and verify the resolved php / laravel/framework / laravel/horizon constraints against the target application's composer.json before merging. The release note asserts support; Composer's solver is the authority.

Sequencing.

1. Confirm Horizon is present and healthy in the target environment (prerequisite, not part of this change).
2. Add the dependency on a feature branch; run composer update huangdijia/laravel-horizon-restart --with-dependencies to see the full transitive delta.
3. Publish and review config; explicitly disable or gate any auto-registered route.
4. Attach authorization middleware, IP allowlist, and rate limiter; add audit logging (actor, timestamp, target node, outcome).
5. Validate in staging: confirm workers actually cycle, confirm in-flight job behavior matches expectations, confirm the endpoint fails closed when unauthorized.
6. Roll out to one production node/canary group behind the restricted surface, then widen.
7. Add a runbook entry and a dashboard panel so restarts are visible events rather than invisible ones.

Alternative to weigh. If the only need is "restart workers on deploy," the first-party php artisan horizon:terminate invoked from the deploy pipeline may satisfy the requirement with zero new dependencies. This package earns its place only when non-engineers or remote operators need the capability without shell access.

Operational Impact

Maintenance. Very low surface area, so low ongoing maintenance — but ownership sits with a single maintainer. Budget for the possibility of fork-and-vendor. The Laravel Shift contribution is a positive signal for upgrade cadence, though it is automation rather than sustained human maintainer depth.

Support. Community OSS, best-effort. No vendor SLA. Internal teams must own the runbook: what a restart does, when to use it, who may invoke it, and how to confirm success.

Scaling. The package itself does not scale — it is stateless. The scaling concern is operational: in a many-node Horizon deployment, restart coverage depends on request fan-out or on Horizon's own supervisor behavior. Confirm whether a per-node call, a load-balanced call, or a broadcast mechanism is required before assuming fleet-wide coverage.

Failure modes to design for.

• Endpoint reachable without auth (critical) — mitigate with middleware + network policy.
• Restart returns success but workers did not cycle (wrong node, Horizon not running) — mitigate with post-restart verification, not status-code trust.
• Restart storms from repeated calls or a retry loop — mitigate with rate limiting and idempotency guards.
• Job loss/duplication during restart — mitigate at the application layer: idempotent jobs, sane retry_after > timeout, graceful termination.
• Package abandonment blocking a future Laravel major — mitigate by keeping the wrapper thin and treating it as replaceable.

Ramp-up. Minimal for a Laravel-fluent engineer (hours). The real ramp is not technical — it is procedural: training operators that "restart Horizon" is a production action with queue-durability implications, and that a 200 response is not proof of success.

Recommendation. Adopt v3.1.0 if the org is on Horizon, needs remote restart capability, and is willing to fund the auth + audit + verification work around it. Do not adopt it as the sole mechanism for deploy-time worker recycling. Track the Laravel 13 / PHP 8.5 compatibility window as the next meaningful review trigger.