PHPackages                             friendsofphp/consul-php-sdk - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. friendsofphp/consul-php-sdk

ActiveLibrary[API Development](/categories/api)

friendsofphp/consul-php-sdk
===========================

SDK to talk with consul.io API

v5.3.0(5mo ago)316230.5k↓12.3%555MITPHPPHP >=8.1CI passing

Since Dec 8Pushed 5mo ago14 watchersCompare

[ Source](https://github.com/FriendsOfPHP/consul-php-sdk)[ Packagist](https://packagist.org/packages/friendsofphp/consul-php-sdk)[ RSS](/packages/friendsofphp-consul-php-sdk/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (4)Dependencies (3)Versions (16)Used By (5)

Consul PHP SDK
==============

[](#consul-php-sdk)

Consul PHP SDK is a thin wrapper around the [Consul](https://consul.io/) HTTP API.

Compatibility
-------------

[](#compatibility)

See previous version of [README.md](https://github.com/FriendsOfPHP/consul-php-sdk/tree/404366acbce4285d08126c0a55ace84c10e361d1)to find some version compatible with older version of symfony/http-client or guzzle

Installation
------------

[](#installation)

This library can be installed with composer:

```
composer require friendsofphp/consul-php-sdk

```

Supported services
------------------

[](#supported-services)

- agent
- catalog
- health
- kv
- session
- txn

Usage
-----

[](#usage)

Instantiate a services, and start using it:

```
$kv = new Consul\Services\KV();

$kv->put('test/foo/bar', 'bazinga');
$kv->get('test/foo/bar', ['raw' => true]);
$kv->delete('test/foo/bar');
```

A service exposes few methods mapped from the consul [API](https://consul.io/docs/agent/http.html):

**All services methods follow the same convention:**

```
$response = $service->method($mandatoryArgument, $someOptions);
```

- All API mandatory arguments are placed as first;
- All API optional arguments are directly mapped from `$someOptions`;
- All methods return a `Consul\ConsulResponse`;
- If the API responds with a 4xx response, a `Consul\Exception\ClientException` is thrown;
- If the API responds with a 5xx response, a `Consul\Exception\ServeException` is thrown.

Cookbook
--------

[](#cookbook)

### How to acquire an exclusive lock?

[](#how-to-acquire-an-exclusive-lock)

```
$session = new Consul\Services\Session();

$sessionId = $session->create()->json()['ID'];

// Lock a key / value with the current session
$lockAcquired = $kv->put('tests/session/a-lock', 'a value', ['acquire' => $sessionId])->json();

if (false === $lockAcquired) {
    $session->destroy($sessionId);

    echo "The lock is already acquire by another node.\n";
    exit(1);
}

echo "Do you jobs here....";
sleep(5);
echo "End\n";

$kv->delete('tests/session/a-lock');
$session->destroy($sessionId);
```

### How to use MultiLockHandler?

[](#how-to-use-multilockhandler)

```
$resources = ['resource1', 'resource2'];

$multiLockHandler = new MultiLockHandler($resources, 60, new Session(), new KV(), 'my/lock/');

if ($multiLockHandler->lock()) {
    try {
        echo "Do you jobs here....";
    } finally {
        $multiLockHandler->release();
    }
}
```

### How to use MultiSemaphore?

[](#how-to-use-multisemaphore)

```
$resources = [
    new Resource('resource1', 2, 7),
    new Resource('resource2', 3, 6),
    new Resource('resource3', 1, 1),
];

$semaphore = new MultiSemaphore($resources, 60, new Session(), new KV(), 'my/semaphore');

if ($semaphore->acquire()) {
    try {
        echo "Do you jobs here....";
    } finally {
        $semaphore->release();
    }
}
```

Some utilities
--------------

[](#some-utilities)

- `Consul\Helper\LockHandler`: Simple class that implement a distributed lock
- `Consul\Helper\MultiLockHandler`: Simple class that implements a distributed lock for many resources
- `Consul\Helper\MultiSemaphore`: Simple class that implements a distributed semaphore for many resources

Run the test suite
------------------

[](#run-the-test-suite)

You need a consul agent running on `localhost:8500`.

But you ca override this address:

```
export CONSUL_HTTP_ADDR=172.17.0.2:8500

```

If you don't want to install Consul locally you can use a docker container:

```
docker run -d --name=dev-consul -e CONSUL_BIND_INTERFACE=eth0 consul

```

Then, run the test suite

```
vendor/bin/simple-phpunit

```

###  Health Score

64

—

FairBetter than 99% of packages

Maintenance72

Regular maintenance activity

Popularity56

Moderate usage in the ecosystem

Community35

Small or concentrated contributor base

Maturity80

Battle-tested with a long release history

 Bus Factor1

Top contributor holds 72.7% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~286 days

Recently: every ~329 days

Total

15

Last Release

159d ago

Major Versions

v1.0.0 → v2.0.02016-07-05

v2.1.0 → v3.0.02017-07-25

v3.1.1 → v4.0.02020-12-01

v4.2.1 → v5.0.02022-06-13

PHP version history (3 changes)v3.0.0PHP >=5.5

v5.0.0PHP >=7.4

v5.2.0PHP >=8.1

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/47313?v=4)[Fabien Potencier](/maintainers/fabpot)[@fabpot](https://github.com/fabpot)

![](https://www.gravatar.com/avatar/c06557c871a39a7ff7f83bd03aa85dc381147cd7dcd83504400f0acd2fda7835?d=identicon)[lyrixx](/maintainers/lyrixx)

---

Top Contributors

[![lyrixx](https://avatars.githubusercontent.com/u/408368?v=4)](https://github.com/lyrixx "lyrixx (72 commits)")[![mpash-bushel](https://avatars.githubusercontent.com/u/225085375?v=4)](https://github.com/mpash-bushel "mpash-bushel (6 commits)")[![jlekowski](https://avatars.githubusercontent.com/u/1238363?v=4)](https://github.com/jlekowski "jlekowski (3 commits)")[![kochen](https://avatars.githubusercontent.com/u/106042?v=4)](https://github.com/kochen "kochen (3 commits)")[![Nek-](https://avatars.githubusercontent.com/u/972456?v=4)](https://github.com/Nek- "Nek- (2 commits)")[![Gufran](https://avatars.githubusercontent.com/u/2152267?v=4)](https://github.com/Gufran "Gufran (2 commits)")[![jippi](https://avatars.githubusercontent.com/u/22841?v=4)](https://github.com/jippi "jippi (1 commits)")[![jsol](https://avatars.githubusercontent.com/u/8709156?v=4)](https://github.com/jsol "jsol (1 commits)")[![kufd](https://avatars.githubusercontent.com/u/1074793?v=4)](https://github.com/kufd "kufd (1 commits)")[![romainneutron](https://avatars.githubusercontent.com/u/137574?v=4)](https://github.com/romainneutron "romainneutron (1 commits)")[![andre-exads](https://avatars.githubusercontent.com/u/54406757?v=4)](https://github.com/andre-exads "andre-exads (1 commits)")[![tusharkant](https://avatars.githubusercontent.com/u/12033035?v=4)](https://github.com/tusharkant "tusharkant (1 commits)")[![artospaj](https://avatars.githubusercontent.com/u/11021356?v=4)](https://github.com/artospaj "artospaj (1 commits)")[![benschw](https://avatars.githubusercontent.com/u/98852?v=4)](https://github.com/benschw "benschw (1 commits)")[![bfeaver](https://avatars.githubusercontent.com/u/441396?v=4)](https://github.com/bfeaver "bfeaver (1 commits)")[![frozzare](https://avatars.githubusercontent.com/u/14610?v=4)](https://github.com/frozzare "frozzare (1 commits)")[![iam2c](https://avatars.githubusercontent.com/u/15009189?v=4)](https://github.com/iam2c "iam2c (1 commits)")

---

Tags

consulconsul-sdkphpsdksdkhashicorpconsul

### Embed Badge

![Health badge](/badges/friendsofphp-consul-php-sdk/health.svg)

```
[![Health](https://phpackages.com/badges/friendsofphp-consul-php-sdk/health.svg)](https://phpackages.com/packages/friendsofphp-consul-php-sdk)
```

###  Alternatives

[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.4k5.6M651](/packages/sylius-sylius)[temporal/sdk

Temporal SDK

4002.2M18](/packages/temporal-sdk)[storyblok/php-content-api-client

PHP Client for Storyblok Content API

11136.8k4](/packages/storyblok-php-content-api-client)[webit/w-firma-api

wFirma.pl API

1820.2k](/packages/webit-w-firma-api)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)