Consul Php Sdk Laravel Package

Product Decisions This Supports

• Infrastructure-backed feature bets. The helpers (LockHandler, MultiLockHandler, MultiSemaphore) turn "make sure only one worker runs this job" or "cap concurrent calls to a third-party API" from a design project into a library call. Frame the decision explicitly as build vs. buy for coordination primitives: custom DB/Redis locking vs. Consul sessions via this SDK.
• Dynamic configuration and feature flags. KV plus the newly whitelisted blocking queries and consistency modes enables push-style config propagation instead of polling — a lever for zero-downtime deploys, per-tenant config, and kill switches without redeploying PHP-FPM.
• Service discovery roadmap. Agent / Catalog / Health cover registration, inventory, and health-driven routing. Relevant if you are splitting a monolith or adding a second region (dc option now accepted on non-local endpoints).
• Platform/ops tooling build-vs-buy. Snapshot (backup/DR runbooks), Operator (cluster admin), ACL (programmatic policy management), Event (deploy coordination) — v5.4.0 means internal admin tooling no longer needs a Go sidecar. If your platform team was going to write those scripts anyway, this retires that work.
• Build vs. buy, overall. The buy case is "free, MIT, thin wrapper, whole Consul CE HTTP API covered — we don't write or maintain a client." The honest caveat for the decision record: adopting the SDK implies adopting Consul, which is the real cost. The SDK decision is small; the Consul decision is not.
• Migration/administrative decisions. The package was renamed sensiolabs/consul-php-sdk → friendsofphp/consul-php-sdk (v5.0.0, namespace change to Consul\). If any team, doc, or Composer constraint references the old name, that is a small but real ticketed migration — worth resolving before a roadmap commitment rather than during it.
• Use cases to prioritize: scheduled/background job coordination; multi-tenant config; gradual monolith-to-service extraction sharing config via KV; multi-region routing with dc + Peering.

When to Consider This Package

Adopt if:

• Consul is already running, or is already committed on the roadmap. Without the server, this dependency delivers nothing — it is a client.
• You are on PHP 8.2+ and symfony/http-client 6.4+ (v5.4.0 hard gate; psr/log 2.x/3.x). Confirm the Laravel version in use is compatible with that HTTP client line.
• You want framework-agnostic, container-bound usage. It is not a Laravel package — no service provider, no facade, no publishable config. You bind Consul\ClientInterface yourself. That is fine, and cheap, if you know it up front.
• You need the long tail: ACL tokens via CONSUL_HTTP_TOKEN, blocking queries, dc, multi-valued options like ['tag' => ['v1','primary']], typed 4xx/5xx exceptions via ClientException/ServerException.
• You value maintainability signals: modernized codebase (readonly classes, constructor property promotion, PHPUnit 11+), documented upgrade path, changelog discipline under FriendsOfPHP.

Look elsewhere if:

• You are on PHP 8.1 or Symfony 5.4. This is the gating change, not a footnote. Either pin to 5.3.x or fund the platform upgrade first — cost that before you cost the integration.
• There is no Consul and no appetite to operate it. Redis-backed atomic locks, database config, or cloud-native discovery will be cheaper in total. Do not adopt this to avoid an infra decision; it is an infra decision.
• You need Consul Enterprise (namespaces, admin partitions, license management). CE only — now explicitly bounded.
• You need Consul ACME / Connect specifics. Connect coverage is new in 5.4.0; validate the exact endpoints in a spike before putting mTLS intentions on a delivery date.
• You want a first-class Laravel experience (facade, queue driver, health-check integration, config publishing). You will write that glue; budget it, or evaluate a Laravel-native alternative on total effort rather than on the SDK's surface area.
• Ecosystem support depth matters. 317 stars and 0 known dependents means a thin community: few blog posts, few StackOverflow answers, and reliance on the maintainer plus the source. Answer "can we fork and carry this?" in the architecture review — the code is small and MIT, so the answer is usually yes, but say it out loud.
• Verify release metadata before quoting it. The listing shows a last release dated 2026-09-29, which cannot be right relative to today; confirm the actual latest tag and changelog in Packagist before it appears in a deck.

How to Pitch It (Stakeholders)

For executives. This is a free, MIT-licensed, small PHP library that lets our PHP services participate directly in Consul — service discovery, dynamic configuration, and distributed locks — instead of us commissioning a bespoke client. It converts a multi-sprint build into a wiring task and is maintained under FriendsOfPHP with a disciplined changelog and a modernized codebase. Two things to be clear about: the library is cheap, but the platform it talks to (Consul) carries the real operating cost, so this is only a good deal if Consul is already part of our infrastructure or roadmap; and it is a small-community project, so we should approve it with a named owner and a fork contingency, not as a set-and-forget dependency.

For engineering. Thin wrapper over the Consul CE HTTP API with a uniform $service->method($required, $options) convention, a ConsulResponse wrapper, and typed ClientException / ServerException for 4xx/5xx. v5.4.0 covers the whole CE API — Agent, Catalog, Health, KV, Session, Txn, plus ACL, Config, Connect, Coordinate, DiscoveryChain, Event, Operator, Peering, PreparedQuery, Snapshot, Status — and whitelists blocking queries, consistency modes, filtering, and dc. Requirements are the decision point: PHP ≥ 8.2, symfony/http-client ≥ 6.4, psr/log 2.x/3.x. In Laravel it is not auto-wired: bind Consul\ClientInterface in a service provider, add a config/consul.php reading CONSUL_HTTP_TOKEN, and inject the service classes where needed. Before committing, run a short spike on the three things that actually bite: lock and session behaviour under clock skew and session TTL, blocking-query timeouts under PHP-FPM worker limits, and token delivery via environment versus cached config.