Weave Code
Consul Php Sdk Laravel Package
friendsofphp/consul-php-sdk
A thin PHP wrapper around the Consul HTTP API, covering agent, catalog, health, kv, session, and txn services. It returns ConsulResponse objects, throws typed exceptions, and includes helpers for locks and semaphores.
Consul PHP SDK is a thin, dependency-light wrapper around the Consul HTTP API for PHP. Install it via Composer and instantiate services like Consul\Services\KV to interact with Consul directly. All methods return a Consul\ConsulResponse, and API errors are surfaced as ClientException (4xx) or ServeException (5xx).
- Supports agent, catalog, health, kv, session, and txn services
- Consistent API: mandatory arguments first, optional arguments as an options array
- Built-in cookbook recipes for exclusive locks and distributed semaphores
- Includes MultiLockHandler and MultiSemaphore helpers for coordinating resources
Frequently asked questions about Consul Php Sdk
- How do I install friendsofphp/consul-php-sdk with Composer?
- Run composer require friendsofphp/consul-php-sdk; v5.4 requires PHP 8.2 or newer and pulls in symfony/http-client 6.4, 7.4 or 8.1+ along with psr/log 2.x or 3.x. There is no Laravel auto-discovery service provider, so you normally register the service classes in your own provider. If your application still pins psr/log ^1.0 you will hit a Composer resolution conflict and should resolve it before installing.
- Does this Consul SDK work with Laravel, or is it framework agnostic?
- It is a framework-agnostic PHP SDK with no Laravel dependency, so it runs in any PHP 8.2+ project including Laravel. In Laravel you typically bind Consul\Services\KV, Session, Health and Catalog as singletons in a service provider and resolve them from the container. Because v5.4 moves to immutable readonly classes, wrap SDK calls behind your own interfaces so tests stay easy to fake.
- Which PHP and Laravel versions does consul-php-sdk v5.4 support?
- v5.4 sets a hard PHP 8.2 floor, up from PHP 8.1 in v5.3, so a Laravel 9 or 10 app still on PHP 8.1 cannot upgrade without a runtime bump. Symfony 5.4 support is dropped and psr/log 1.x is no longer allowed. If you cannot move the runtime yet, stay on v5.3.x or use the older tag that matches your symfony/http-client or Guzzle version.
- Which Consul API endpoints can I call from PHP with this SDK?
- The core services are agent, catalog, health, kv, session and txn, and v5.4 extends coverage across the Consul CE HTTP API including ACL, Config, Connect, Coordinate, DiscoveryChain, Event, Operator, Peering, PreparedQuery, Snapshot and Status. Each service mirrors the Consul HTTP API, with mandatory arguments first and optional parameters passed as an options array. Every call returns a Consul\ConsulResponse object, so you can call json() or inspect the raw HTTP response.
- How does consul-php-sdk report Consul API errors?
- A 4xx response from Consul throws Consul\Exception\ClientException, while a 5xx response throws the SDK's server-side exception class, so you can catch them separately and map them to Laravel's exception handler or retry logic. Successful calls return a ConsulResponse you convert with json(). This keeps error handling explicit instead of forcing you to check status codes on every call.
- How do I implement a distributed lock or semaphore with Consul in PHP?
- Create a session with Session::create(), then pass its ID as the acquire option when writing the KV key; a false result means another node already holds the lock. The SDK ships MultiLockHandler and MultiSemaphore helpers plus a Resource class for weighted semaphores that acquire and release several keys at once. Always release in a finally block and destroy the session afterwards, because Consul only frees a lock when the session ends.
- How do I configure the Consul agent address and ACL token?
- Services talk to the Consul HTTP API, so you point them at your agent address and supply an ACL token; v5.4 also supports a CONSUL_HTTP_TOKEN environment fallback that simplifies bootstrapping. Keep the token in config/services.php or a secrets manager rather than in version control, and remember that once it is in the environment any code path can read it. Endpoints that are not agent-local now accept a dc parameter, so cross-datacenter calls no longer silently hit the local datacenter.
- Can I run Consul blocking queries or watch the service catalog from PHP?
- Yes. Blocking queries, wait, index and consistency mode are now first-class, whitelisted options on the service methods, so you can long-poll the catalog, health or KV endpoints instead of hand-rolling index and wait parameters. This is the simplest way to react to service registration changes in PHP without a separate agent-side watcher. Run long polls inside a queue worker or dedicated process rather than inside a normal web request.
- What production risks should I review before using this SDK?
- v5.4 reaches powerful endpoints: Snapshot restore is cluster-wide and destructive, and Operator or ACL calls can change Raft membership or mint tokens, so scope the ACL token each application uses and never give a web app agent:write or operator rights. Also note that Agent::join() and Agent::forceLeave() now correctly use PUT, meaning code that called them defensively will actually mutate cluster membership after the upgrade. Re-validate lock semantics too, since Session::create() and MultiSemaphore fixes change behavior that was previously silently incorrect.
- Is consul-php-sdk maintained, and what are the alternatives?
- It is maintained by the FriendsOfPHP community with tagged releases such as v5.4.0, so check recent commits and the README compatibility notes before adopting it. HashiCorp publishes no official PHP client, so the main alternatives are calling the Consul HTTP API directly through Laravel's Http facade or Guzzle, or older community clients that may lag behind current Consul features. This SDK is the pragmatic pick when you want typed services, response objects and built-in locking helpers.
Weaver
How can I help you explore Laravel packages today?