Weave Code
Consul Php Sdk Laravel Package
sensiolabs/consul-php-sdk
A thin PHP wrapper around the Consul HTTP API, covering agent, catalog, health, kv, session and txn services. Methods return a ConsulResponse and throw exceptions on 4xx/5xx errors, with handy lock and semaphore helpers for distributed coordination.
SDK to talk with consul.io API
Frequently asked questions about Consul Php Sdk
- How do I install Consul PHP SDK in a Laravel application?
- Use Composer to install the SDK; the README shows composer require friendsofphp/consul-php-sdk, while this package metadata lists sensiolabs/consul-php-sdk, so confirm the active package name in your registry. The SDK is framework-agnostic, so bind the Consul service classes in a Laravel service provider or wrap them in a facade. Version 5.4 requires PHP 8.2 or newer.
- Which Laravel and PHP versions are supported by consul-php-sdk 5.4?
- Version 5.4 requires PHP 8.2 or newer, which Laravel 11 and Laravel 12 already require. Laravel 10 apps still on PHP 8.1 must pin ^5.3, and Laravel 9 is out of scope for 5.4. The dependency floors also move to symfony/http-client 6.4, 7.4, or 8.1+ and psr/log 2.x or 3.x, so check for Symfony 5.4 LTS or Monolog 2 before upgrading.
- Which Consul API services does this PHP SDK cover?
- The core services are agent, catalog, health, kv, session, and txn. Version 5.4 expands coverage to the whole Consul CE HTTP API, adding ACL, Config, Connect, Coordinate, DiscoveryChain, Event, Operator, Peering, PreparedQuery, Snapshot, and Status. It also adds missing endpoints on Agent, Catalog, and Health.
- How do I configure CONSUL_HTTP_TOKEN and Consul endpoints in Laravel?
- The SDK reads CONSUL_HTTP_TOKEN from the environment, which aligns with Laravel env and secrets handling and removes a custom token binding line. Configure your Consul address and datacenter options through service construction or container bindings. Inject those configured service objects into controllers, jobs, and console commands rather than creating clients inline.
- Can I use this SDK for distributed locks and semaphores in Laravel?
- Yes. It includes MultiLockHandler and MultiSemaphore helpers built on Consul sessions and KV. Version 5.4 fixes Session::create() for the no-argument case and prevents MultiSemaphore from reusing a prior resource's metadata. If a previous spike rejected this SDK for distributed locks, re-run it because that result is stale, and always release locks in a finally block.
- Can I manage canary releases and weighted traffic splitting from Laravel with this SDK?
- Yes. The Config service exposes Consul config entries such as service-router, service-splitter, service-resolver, and service-defaults. That enables canary and weighted traffic split for Laravel services without an ingress rewrite. Re-scope this with your platform or DevOps owner because it moves release control into Consul.
- Does Consul PHP SDK support Connect, mTLS, and intentions?
- Yes. The Connect service allows programmatic intention and mTLS management from Laravel instead of hand-editing HCL. This directly addresses service mesh security risk around mTLS. Treat it as a control-plane operation and coordinate changes with the platform or DevOps owner.
- How do I handle multi-datacenter failover, backups, and HA with this SDK?
- PreparedQuery supports multi-datacenter failover plus tag- and filter-based lookups, which is stronger than raw Catalog::service() calls. Snapshot exposes save and restore of Consul state, closing the backup gap. Peering plus the dc option on non-agent-local endpoints enables cross-datacenter routing from one Laravel codebase, while Operator and Status services expose raft, autopilot, leader, and peer health.
- Should I use Consul KV or Config entries for Laravel application settings?
- Use KV for ordinary application settings, and use Config entries for mesh and service configuration such as routers, splitters, resolvers, and defaults. Consul events are best-effort and non-durable, so use them for deploy or orchestration hooks, not as a replacement for Laravel queues. Blocking queries are documented in v5.4, so prefer long-poll watches in a console or queue worker over Cache::remember polling.
- How should I test and upgrade a Laravel app that uses Consul PHP SDK?
- Test at the service boundary by mocking container-bound Consul services or stubbing HTTP, and assert ConsulResponse results, 4xx ClientException paths, 5xx exception paths, and lock release in finally blocks. Before upgrading from 5.3 to 5.4, inventory PHP 8.2, symfony/http-client, and psr/log versions, then pin ^5.3 where upgrades lag. Re-run any stale lock-handler spike because the Session::create() fix changes the result. Laravel 9 remains out of scope for 5.4.
Weaver
How can I help you explore Laravel packages today?