Consul Php Sdk Laravel Package

Product Decisions This Supports

• Service discovery: build vs. buy gets a clear answer. Consul registration, catalog lookup, and health checking are solved primitives once you run Consul. This SDK makes the PHP side a thin, low-code integration rather than a maintained internal HTTP client. The decision to revisit is not "should we write our own client" — it's "should we run Consul at all."
• Roadmap sequencing for distributed-systems features. The three helpers (LockHandler, MultiLockHandler, MultiSemaphore) are the highest-leverage part of the package for a PM, because they convert "distributed locking" from an engineering epic into a small, testable increment. That supports a phased roadmap: (1) config/KV + service discovery, (2) leader election and exclusive jobs via sessions and locks, (3) throttled/concurrency-limited workers via semaphores, (4) service mesh and cross-cluster work.
• Scoping concurrency and "exactly one worker" requirements. Cron overlap, duplicate queue consumers, single-node migrations, and per-tenant rate limits are recurring stakeholder asks. MultiSemaphore with per-resource limits lets you promise "at most N concurrent syncs per tenant" as a product guarantee rather than an aspiration — and the 5.4.0 fix for multi-resource acquisition means that guarantee actually holds across many resources.
• Feature breadth is no longer a blocker. v5.4.0 covers the whole Consul CE HTTP API, including ACLs, prepared queries, Connect, peering, snapshots, and operator/status endpoints. Concretely, this means "blocking queries" and consistency modes become first-class options — a latency and freshness decision a PM can make (fast reads vs. strongly consistent reads) instead of a negotiation with engineering about custom query strings.
• DR and compliance story you can put in a review. The new Snapshot service makes "we can back up and restore our coordination state" an automated, auditable capability from application tooling. That is a concrete deliverable for a SOC2/ISO control narrative rather than a manual runbook item owned by one person.
• Cross-cluster and hybrid-cloud is a product option, not a platform veto. Peering plus dc support on all non-agent-local endpoints means multi-region or hybrid rollouts can be scripted from PHP. This moves "expand to a second region" from an unestimated platform project into a scoped application-team workstream.
• Budget for the Laravel glue, explicitly. This is a framework-agnostic SDK — no service provider auto-discovery, no config/consul.php, no facades. Adoption implies a small but real internal package (provider + config + a health-check wrapper). Size it as a 1–2 day task and assign an owner; otherwise it silently becomes everyone's and no one's.
• Couple the adoption decision with the platform upgrade. PHP ≥ 8.2, symfony/http-client ≥ 6.4, and psr/log ≥ 2 are floors on a nominally minor release. Treat "adopt this SDK" and "upgrade the runtime" as one work item with one owner and one deadline, or the upgrade will surface mid-sprint as a lockfile conflict.
• Risk register entry: 0 dependents. Low third-party adoption is a real signal. The mitigation is straightforward — MIT license, FriendsOfPHP stewardship, active releases, and a narrow API surface mean an escape hatch is cheap — but it argues for keeping Consul usage behind your own thin abstraction rather than calling Consul\Services\* directly throughout the codebase.

When to Consider This Package

Adopt if:

• You are on PHP 8.2+ (or can get there as part of the same initiative) and need Consul for service discovery, KV config, sessions, or coordination.
• You are already running Consul, or the Consul cluster is a committed platform decision. The SDK is the cheap half; the cluster is the expensive half.
• You have a genuine distributed-coordination need — leader election, exclusive scheduled jobs, per-tenant concurrency caps — where a single Redis lock is insufficient.
• You need API breadth (ACLs, prepared queries, Connect, peering, snapshots) that would otherwise be hand-rolled raw HTTP in a codebase nobody owns.
• You want CONSUL_HTTP_TOKEN standard-env token handling to match your container and CI conventions.
• MIT licensing and active maintenance are compliance requirements.

Look elsewhere if:

• You need Consul Enterprise (namespaces, admin partitions, SSO, redundancy zones, Sentinel). The ACL service here is CE ACLs, not enterprise governance — do not let this package create the impression that enterprise controls are covered.
• Your only real need is cached key-value lookups or a simple mutex. Redis, Laravel's cache locks, or etcd are simpler and impose no cluster to operate.
• You are pinned to PHP 8.1, symfony/http-client 5.4, or psr/log 1.x. Stay on 5.3; 5.4 will not install, and forcing it will cascade into a broader framework upgrade.
• You expect a drop-in Laravel package with publishing, facades, and lifecycle hooks. This is a transport-layer SDK; you are buying the API mapping, not the framework integration.
• Your stack is Go, Java, or Python, where native Consul clients are more mature and better documented.

Before committing, verify:

• Lockfile resolution end-to-end in a branch — the dependency floors can ripple wider than expected in a Laravel app.
• That someone owns the Consul cluster itself: upgrades, backups, ACL bootstrapping, and agent monitoring. The SDK makes Consul easy to call, not easy to operate, and unowned infrastructure is the most common way this decision fails quietly.

How to Pitch It (Stakeholders)

For executives: We need three things that are currently hand-built or missing — reliable service discovery as we split the monolith, a guarantee that scheduled jobs and syncs don't run twice, and a backup story for the coordination layer everything depends on. This package is a small, MIT-licensed, actively maintained library from the FriendsOfPHP/Symfony ecosystem that covers all three with about a day of integration work on our side. The cost is not the library; it is a runtime upgrade to PHP 8.2, which we have on the roadmap anyway and should now schedule deliberately rather than discover mid-sprint. The main risk is operational: adopting this means committing to running Consul well, with a named owner.

For engineering: It is a thin wrapper over Consul's HTTP API with consistent method signatures, typed 4xx/5xx exceptions, and full coverage of the Consul CE API as of v5.4.0 — including blocking queries, consistency modes, and multi-valued options as first-class arguments. The genuinely useful part is the helper layer: LockHandler, MultiLockHandler, and MultiSemaphore give us distributed locks and concurrency limits without writing our own session/acquire/release logic. Two caveats: it is framework-agnostic, so we write our own service provider and config; and it has near-zero external dependents, so we should route calls through a single internal adapter class rather than referencing Consul\Services\* throughout the codebase, keeping the swap cost low. Budget the PHP 8.2 and symfony/http-client upgrade as part of the same ticket.