Oc Horizon Plugin Laravel Package

Technical Evaluation

What the package is. vdlp/oc-horizon-plugin is an adapter that installs Laravel Horizon — Laravel's first-party Redis queue dashboard and supervisor orchestrator — into October CMS's backend. The value proposition is narrow but real: queue throughput, wait times, failed-job retry/delete, and supervisor configuration exposed inside the CMS the team already logs into, instead of a bespoke dashboard, redis-cli, or raw failed_jobs queries. The underlying capability (Horizon) is well-understood and stable; only the glue is third-party.

Architecture fit. Reasonable at the framework layer — October runs on Laravel, so Horizon's service provider, routes, and assets can be registered through October's plugin lifecycle. The fit is imperfect at three seams a TPM should note as acceptance criteria, not implementation trivia: (1) service-provider and route registration inside October's Plugin::register()/boot() rather than a stock AppServiceProvider; (2) authorization, where Horizon expects a Laravel Gate/Horizon::auth callback but October supplies its own backend user, role, and permission model; (3) asset publishing and URL prefixing, which diverge from stock Laravel's public/vendor/horizon. Each seam is a place where an upgrade to either parent project can break behavior silently.

Integration feasibility. High for an October CMS estate already running queues on Redis. Low-to-zero value otherwise — Horizon only manages Redis connections, so a database or sync queue yields an empty dashboard and a false sense of coverage. The real cost is not the plugin but its prerequisites: a reachable Redis instance in every environment where Horizon runs, a process supervisor for the horizon daemon, and a deploy pipeline that terminates Horizon on release. None of that is delivered by the package.

Technical risk — the dominant issue is maintenance status. The repository is archived. That reframes the evaluation entirely: there is no upstream fix path for a Horizon major bump, an October major bump, a PHP version floor, or a security issue in the adapter. Adoption means the team inherits ownership of the adapter, whether or not anyone has said so out loud. Compounding this:

• Release opacity. 3.4.0 (the last release, 2025-07-04) ships an auto-generated compare link and nothing else. A minor bump could carry a raised version floor, a config key rename, a Horizon major bump, or a permission-handling change — indistinguishable from a bugfix without reading the diff.
• Adoption signal. 8 stars and a single maintainer means no community safety net, no third-party bug reports triaged ahead of yours, no Stack Overflow corpus.
• Licensing. GPL-2.0 is copyleft. Whether that is acceptable depends entirely on distribution model — internal-only use is typically fine; shipping October-based product to customers is a legal question, not an engineering one. This must be resolved before any code is committed.
• Privileged surface. Horizon exposes retry, delete, purge, terminate, and supervisor scaling behind a web route. If the plugin's authorization binding is coarser than "October superuser" or a granular permission, that is an operational-risk finding, not a nit.

Decision framing. Given archived status, the realistic options are: (a) adopt and pin to a known-good tag, accepting that the team owns all future compatibility work; (b) internalize — fork, vendor, or hand-wire Horizon into October directly (Horizon is a documented Laravel package; the adapter is arguably tens of lines of service-provider and navigation registration, which may be cheaper to own than a fork); (c) defer and use Horizon standalone outside the CMS backend meanwhile. A TPM should size option (b) before defaulting to (a) — the build cost may be lower than the fork-maintenance cost, and it removes the GPL and archived-dependency questions simultaneously.

Key questions to close before commitment:

• What changed in 3.3.0 → 3.4.0, and does it raise any october/*, laravel/framework, laravel/horizon, or PHP floor?
• Does the plugin pin Horizon, or inherit the host app's version? Who owns that upgrade — us or nobody?
• How is Horizon's authorization bound to October's permission model, and can it be restricted below "any backend user"?
• Has Legal signed off on GPL-2.0 given our distribution model?
• Is this queue dashboard a funded requirement (SLO, MTTR target, on-call need), or a nice-to-have we are about to take ownership of for free?

Integration Approach

Stack fit gates. Three prerequisites, each a go/no-go: Redis is the queue backend in the environment(s) where Horizon will run; the plugin's declared October/PHP/Laravel constraints match our install; and a process supervisor (systemd, supervisord, or container sidecar) exists or will be built for the horizon daemon. If any is missing, the effort estimate is not "install a plugin" — it is an infrastructure workstream, and should be scoped and sequenced as one.

Migration path. Additive and reversible in principle: Composer require, October migrate, publish Horizon config and assets, bind authorization. No application schema changes beyond Horizon's own tables and Redis keys; no queue payload changes. Rollback is a version pin plus a config-cache clear, with orphaned Horizon Redis keys as the residual — deliberate flush if the connection is shared. This low blast radius is a genuine advantage and makes a staged pilot cheap.

Compatibility verification. Treat 3.4.0 as unverified, not as "probably fine." Pin explicitly to a reviewed tag until the diff is read and a staging run confirms behavior under our PHP/October/Laravel matrix. Check specifically that a Horizon version required transitively by the plugin does not conflict with one already resolved elsewhere in the app — adapter packages that pin transitively are a common source of resolution deadlock.

Sequencing.

1. Legal/licensing review (GPL-2.0) in parallel with engineering spike — do not let these serialize, but do not let code land before the answer.
2. Read the 3.4.0 diff and composer.json deltas; classify patch-equivalent vs. behavioral. This is the cheapest risk-retirement step available.
3. Staging pilot: October instance, Redis, non-production queue, plugin installed, dashboard rendering under the backend route. Dispatch a throwaway job and watch it move pending → processing → completed; kill one deliberately and confirm it lands in Failed with a working retry.
4. Authorization acceptance test: access as superuser, as a backend user without the relevant permission, and logged out. Confirm the route is not reachable unauthenticated. This is a pass/fail gate, not a smoke test.
5. Supervisor configuration and deploy-hook design before production: horizon under systemd/supervisord, and php artisan horizon:terminate inserted into the release sequence (distinct from queue:restart — it drains and respawns supervisors).
6. Sizing exercise for the internalize alternative, so the adopt decision is made against a real comparison rather than by default.
7. Production cutover on one non-critical queue first; expand queue coverage once metrics and alerts are trusted.

Ecosystem fit beyond the pilot. Decide up front whether Horizon's dashboard is the system of record for queue health or a convenience view. If alerting runs off Horizon's waits thresholds and Slack/mail routing, that is a dependency on a package we cannot upgrade independently — worth writing down as an owned risk with a named owner.

Operational Impact

Maintenance ownership is the headline. With the repository archived, "maintenance" is not a vendor activity — it is a line item on our roadmap. Concretely, that means someone must own: watching Laravel/October/Horizon major releases and validating the adapter against them, re-publishing Horizon assets when the bundle drifts (a stale bundle surfaces as a 404 in the dashboard, not an obvious failure), and reviewing each October upgrade for service-provider or permission-model changes. If no team will accept that ownership, the correct outcome is to internalize or defer, not to install and hope.

Support model. No vendor, no SLA, no security response channel. Internal support will be first-line engineers reading source. Budget onboarding time for that reality; it is small code but unfamiliar-to-most glue.

Deployment and change management. The recurring operational cost is process hygiene, and it is easy to get wrong in ways that look like application bugs:

• Every deploy must terminate Horizon; long-lived workers hold cached application code and stale config in memory.
• config/horizon.php edits do nothing until config cache is cleared and Horizon is terminated — the most common cause of "the new supervisor didn't start."
• Supervisor settings for memory, maxJobs, maxTime, tries, timeout must be set explicitly per supervisor; October workers boot the full CMS and accumulate memory and stale DB connections if left on defaults.
• Timeout ordering (job timeout < supervisor timeout < retry_after) must be validated in review; violating it produces duplicate job executions, which are expensive to diagnose and erode trust in the queue.

Failure modes to document and monitor.

• Silent no-op when Redis is down. Horizon starts, logs connection errors, and shows an empty dashboard rather than failing loudly. Operators must know to check redis-cli ping before opening a ticket on the plugin.
• APP_ENV key mismatch in environments causes a fallback to a single worker with no balancing — jobs still process, so nobody notices until latency degrades.
• Upgrade-induced boot failure. Because the plugin wraps a Laravel package and registers a service provider, a bad version bump can surface as an app-wide boot failure rather than an isolated dashboard break. This argues for pinned versions, staged upgrades, and a documented rollback to the prior tag.
• Failed-job schema drift. Horizon upgrades can carry failed_jobs/job_batches migrations; skipping the October migrate step produces exceptions on the first failure after an upgrade — precisely when you need the dashboard to work.
• Dashboard as a privileged surface. Retry/delete/purge/terminate are destructive. Verify the authorization binding, and log who uses them.

Scaling. Horizon's own balancing strategies (simple/auto) are mature and the plugin does not interfere with them meaningfully. Scaling considerations that sit outside the plugin: Redis availability and memory (Horizon stores metrics and supervisor state there — a Redis restart mid-flight is a queue-availability event), and the cardinality of queues. Routing jobs to dedicated queues rather than a single default queue is the highest-leverage configuration change, because per-queue wait-time metrics are what make the dashboard diagnostically useful rather than decorative.

Ramp-up. Engineers: low — one supervised process, one config file, one deploy hook; a half-day for someone already fluent in Laravel queues, longer for anyone who is not, since most of the learning is Horizon's semantics rather than the plugin's. Operations/on-call: moderate — the runbook must cover Redis health, empty-dashboard triage, horizon:terminate on deploy, and the failed-job retry path. Stakeholders: trivial, but worth a short demo — the visibility win is the justification for taking on the maintenance burden, and it should be shown to the people who funded the request.

Net TPM read. The functional gap this closes is real and the integration cost is genuinely low. The lifecycle cost is not: an archived, GPL-2.0, single-maintainer adapter with an undisclosed last release means we are buying a capability and inheriting a dependency. Proceed only with a named internal owner, a pinned version, a legal sign-off, and a documented internalize-or-fork fallback — or spend the equivalent effort wiring Horizon directly and skip the adapter entirely.