Laravel Meridian Laravel Package

Product Decisions This Supports

• Queue infrastructure choice (database vs. Redis/SQS): Meridian now closes the parity gap with Horizon, not just the observability gap. The log auto-scaling strategy means the last strong technical argument for Redis + Horizon — per-queue process allocation — no longer applies. If your roadmap has a "do we need Redis?" decision, this package lets you defer or cancel that migration and keep the simpler, transactional database driver in production.
• Build vs. buy for internal tooling: It replaces a class of homegrown admin screens (job tables, retry buttons, throughput charts, worker status, silenced-job views, autoscaling logic, dev watch mode). Treat "build an internal queue dashboard" and "build queue autoscaling" as solved problems and redirect that engineering effort elsewhere.
• Operational readiness / launch gating: Job history, wait-time detection, failure visibility, and now master-level memory guardrails are the artifacts you need to sign off on reliability for a launch. Shipping this early makes incident reviews and postmortems data-driven rather than anecdotal — useful evidence for release go/no-go.
• Supervisor consolidation: php artisan meridian plus meridian:pause/continue/terminate/status gives pause-and-drain control during deploys and schema migrations. The new memory_limit behavior (finish running jobs, exit code 12, fire MasterSupervisorOutOfMemory) means the supervisor plays nicely with systemd/Kubernetes restart policies instead of leaking. This supports decisions about zero-downtime deployment strategy and maintenance-window requirements.
• Capacity and cost planning: Throughput, workload-per-queue, runtime and wait-time metrics feed headcount/infra sizing conversations. With auto-scaling (simple, auto, and now log), that conversation shifts from "how many workers do we statically provision?" to "what balance strategy and caps do we set?" — a config decision rather than a recurring sizing exercise.
• Alerting policy and on-call design: The waits semantics changed — an unlisted queue now falls back to '*', or 60 seconds when '*' is not set (previously ignored). That is a behavior change with direct on-call consequences: deployments will start emitting long-wait notifications they did not before. Budget a roadmap item to review waits per connection:queue and confirm notification routes before rollout.
• Retention and audit policy: Silenced jobs (silenced, silenced_tags, Silenced contract) are now retained with status silenced and pruned on the same schedule as completed jobs, and they count in metrics. This makes the metrics numbers more trustworthy for SLA reporting but makes meridian:prune a genuine data-retention decision rather than a cleanup detail.
• Developer experience / onboarding cost: meridian:listen gives Horizon-style live reload with no Node or npm dependency — relevant if you want a decision that keeps the dev toolchain PHP-only, or if your team ships in environments where front-end tooling is undesirable.
• Prioritization input: Per-job-class metrics (runtime, failure rate, retries) give you a ranked list of the worst offenders, which is a defensible, data-backed way to justify paying down background-job tech debt versus new features.
• Multi-tenant / multi-app visibility: Bulk import from the jobs table means jobs enqueued by other applications or via pushRaw() still surface. This supports decisions about consolidating queue processing across services.
• Scope boundaries to note in planning: Database driver only; PHP 8.3+ and Laravel 12/13 only; the supervisor requires pcntl/posix. Any roadmap item depending on Redis, SQS, or an older Laravel version is out of scope for this tool.

When to Consider This Package

Adopt when most of the following hold:

• You run Laravel database queues in production (or are about to), and you currently have no first-class job history or UI — just the jobs/failed_jobs tables.
• You want Horizon-style visibility and Horizon-style process autoscaling without introducing Redis as a new operational dependency.
• You are on Laravel 12/13 with PHP 8.3+, or can plan an upgrade alongside adoption.
• You need audit-grade job history (payload, exception, attempts, wait time, runtime, tags) for debugging, support escalations, or SLA reporting.
• You want a dashboard with no front-end build step — a real constraint for small teams or ops-owned tooling. The same holds for local development now that meridian:listen requires neither Node nor npm.
• You need programmatic access: the JSON API (stats, workload, jobs, job detail) is enough to wire into internal status pages or alerting without scraping a UI.
• You want pause/continue/terminate controls for deploy and migration safety, a master memory ceiling that cooperates with your process monitor, and can run the supervisor (Linux/macOS with pcntl/posix).
• You want backlog alerting out of the box via LongWaitDetected mail — but only if you are prepared to configure waits explicitly, given the new '*'/60-second default.
• You are comfortable with the security posture: routes are configurable (namespace, prefix, domain, middleware) and gated by viewMeridian — verify the gate is wired before exposing anything.

Look elsewhere when:

• You are on Redis, SQS, Beanstalkd, or any non-database driver — this is explicitly database-only. Horizon (Redis) or a driver-agnostic APM is the fit.
• You are pinned to Laravel 11 or earlier, or PHP < 8.3. The version floor is hard.
• You need cross-language or cross-framework queue observability — this is Laravel-event-shaped.
• You operate in a Windows or container environment without pcntl/posix and want the built-in supervisor; you can still use the dashboard, history, and meridian:listen, but supervision must come from systemd/Kubernetes. Note that master OOM handling only helps if something is there to restart the process.
• You need long-term retention or warehouse-grade analytics. meridian:prune implies bounded retention, and silenced jobs now consume that same budget; export to your own store if history is a compliance requirement.
• Your organization mandates a single observability vendor (Datadog, New Relic, Sentry) and will not add a self-hosted UI — the JSON API may still be useful, but the dashboard would be redundant.

Maturity caveat: the package has moved from v1.0.0 to v1.6.0 with a steady, Horizon-aligned release cadence — that is a positive maintenance signal and materially lowers the "first release" risk flagged earlier. This particular upgrade carries no migration, but it does introduce config surface (memory_limit, watch) and a behavior change to long-wait defaults that can generate new alerts. Pin the version, review published config and Blade views on upgrade (republish views if you had published them), and re-validate worker heartbeat accuracy for workers started outside the supervisor before making the dashboard the primary interface for on-call.

How to Pitch It (Stakeholders)

For executives (one paragraph): We run background work — order processing, notifications, imports — on Laravel's database queue, and today we cannot see or tune it. Meridian is a free, open-source package that adds a dashboard, supervisor, and autoscaling for that queue: job history, live throughput, per-job and per-queue metrics, retry/cancel from a UI, pause/terminate controls for safe deploys, and automatic worker allocation across queues. It now matches Horizon feature-for-feature — including autoscaling and a silenced-jobs view — which removes our main remaining reason to migrate to Redis, avoiding a new piece of infrastructure and the staff time to operate it, and it replaces any in-house admin tool we would otherwise build. Cost is a PHP/Laravel version upgrade; the risk is now mostly configuration discipline rather than maturity, so we should pilot it on one queue and tune its alert thresholds before relying on it operationally.

For engineering:

• What it is: A Horizon-equivalent for database queues — and now a genuine one. It records every job lifecycle transition from Laravel's queue events, backfills jobs that bypass events (Bus::batch(), Queue::bulk(), pushRaw(), other apps) from the jobs table, and serves a Blade dashboard plus a JSON API.
• Why we'd take it: Horizon-class visibility and autoscaling without Redis. simple/auto/log balancing means we are not hand-rolling worker math, and log prevents one oversized queue from consuming every process. No front-end build step, and meridian:listen gives us dev auto-reload with no Node/npm — it polls the directories in the new watch option and skips cache/vendor/storage.
• What it costs us: PHP 8.3+ and Laravel 12/13 minimums — that upgrade is still the real work item. pcntl/posix needed for the supervisor (Linux is fine; note for Windows dev environments). Config for routes and the viewMeridian gate must be reviewed before exposure, since the dashboard shows payloads and exception traces — treat it as sensitive data and put it behind auth.
• Upgrade notes for this release: composer update only, no migration. Add memory_limit (default 64 MB, 0 disables) and watch to published config if we published it; republish published Blade views to pick up the Silenced tab. Master now exits with code 12 after draining on OOM and fires MasterSupervisorOutOfMemory — wire that event to alerting and make sure our process monitor restarts on non-zero exit.
• Watch out for the alerting change: long-wait detection now falls back to '*', then to 60 seconds if '*' is unset, where unlisted queues were previously ignored. Explicitly set waits per connection:queue (0 to disable) and only configure mail routes deliberately, or we will ship a noisy alert stream on day one.
• Metrics and retention: silenced jobs are now persisted as silenced until meridian:prune removes them alongside completed jobs, and they count toward metrics — better fidelity, but it changes our prune window calculation. Size retention accordingly.
• Operational fit: meridian:snapshot and meridian:prune auto-register in the scheduler, so retention is a config decision rather than custom code. LongWaitDetected with per-connection:queue mail gives us backlog alerting out of the box.
• Pilot plan: one non-critical queue for two to four weeks. Validate: import completeness for batched jobs, heartbeat accuracy for workers started outside the supervisor, prune window appropriate to our retention needs (now including silenced jobs), the new memory_limit behavior under a real OOM, and dashboard access controls. Then expand and retire any stopgap tooling.