PHPackages                             dcarbone/simple-consul-php - 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. [HTTP & Networking](/categories/http)
4. /
5. dcarbone/simple-consul-php

Abandoned → [dcarbone/php-consul-api](/?search=dcarbone%2Fphp-consul-api)Library[HTTP & Networking](/categories/http)

dcarbone/simple-consul-php
==========================

PHP client for the Consul HTTP API

v3.0.0(3w ago)793021[1 issues](https://github.com/dcarbone/php-consul-api/issues)Apache-2.0PHPPHP ^8.2CI passing

Since Jul 12Pushed 1mo ago7 watchersCompare

[ Source](https://github.com/dcarbone/php-consul-api)[ Packagist](https://packagist.org/packages/dcarbone/simple-consul-php)[ Docs](https://github.com/dcarbone/php-consul-api)[ GitHub Sponsors](https://github.com/dcarbone)[ Fund](https://ko-fi.com/dcarbone)[ RSS](/packages/dcarbone-simple-consul-php/feed)WikiDiscussions main Synced 6d ago

READMEChangelog (10)Dependencies (10)Versions (59)Used By (0)

php-consul-api
==============

[](#php-consul-api)

[![Tests](https://github.com/dcarbone/php-consul-api/actions/workflows/tests.yaml/badge.svg)](https://github.com/dcarbone/php-consul-api/actions/workflows/tests.yaml)

PHP client for the [Consul HTTP API](https://www.consul.io/docs/agent/http.html)

This library is loosely based upon the [official GO client](https://github.com/hashicorp/consul/tree/main/api).

PHP Compatibility
-----------------

[](#php-compatibility)

- `v3.x` requires **PHP 8.2+**.

Version Compatibility
---------------------

[](#version-compatibility)

PHPConsulAPI VersionConsul Version0.3.x0.6.40.6.x0.7-0.8v1.x0.9-currentv2.x0.9-currentv3.x0.9-currentdev-maincurrentNewer versions of the api lib will probably work in a limited capacity with older versions of Consul, but no guarantee is made and backwards compatibility issues will not be addressed.

### V3 Breaking Changes

[](#v3-breaking-changes)

There are a couple breaking changes between v2 and v3:

1. The `FakeMap` class has been removed.
2. The `FakeSlice` class has been removed.
3. The `ReadableDuration` class has been removed.
4. All models now have parameterized constructors.
    - For the life of V3 I will continue to support construction from associative arrays, but the parameterized constructors are the preferred method of construction.
    - Construction via associative array will be removed entirely in V4 (whenever I get around to that).
5. All of that `Transcoding` nonsense has been removed.
6. The root `Config` class may no longer be constructed with a map. You must use constructor parameters.
7. Map-like fields are represented in PHP as associative arrays (for example, `array`); some JSON object inputs may still be accepted as `\stdClass` at setter boundaries.

Composer
--------

[](#composer)

This lib is designed to be used with [Composer](https://getcomposer.org)

Require Entry:

```
{
    "require": {
        "dcarbone/php-consul-api": "^v3.0"
    }
}
```

Configuration
-------------

[](#configuration)

First, construct a [Config](./src/Config.php). This class is modeled quite closely after the [Config Struct](https://github.com/hashicorp/consul/blob/7736539db5305d267b2fd4faa6e86590ca20e556/api/api.go#L339) present in the [Consul API Subpackage](https://github.com/hashicorp/consul/tree/v1.17.2/api).

### Default Configuration

[](#default-configuration)

If you have defined some of the [Consul Environment Variables](https://www.consul.io/docs/agent/options.html)on your hosts then it would probably be easiest to simply execute the following:

```
$config = \DCarbone\PHPConsulAPI\Config::newDefaultConfig();
```

### Advanced Configuration

[](#advanced-configuration)

You may alternatively define values yourself:

```
$config = new \DCarbone\PHPConsulAPI\Config(
    // required fields
    HttpClient: $client,            // [required] Client conforming to GuzzleHttp\ClientInterface
    Address: 'address of server',   // [required]

    // optional fields
    Scheme: 'http or https',            // [optional] defaults to "http"
    Datacenter: 'name of datacenter',   // [optional]
    HttpAuth: 'user:pass',              // [optional]
    WaitTime: '0s',                     // [optional] amount of time to wait on certain blockable endpoints.  go time duration string format.
    Token: 'auth token',                // [optional] default auth token to use
    TokenFile: 'file with auth token',  // [optional] file containing auth token string
    InsecureSkipVerify: false,          // [optional] if set to true, ignores all SSL validation
    CAFile: '',                         // [optional] path to ca cert file, see http://docs.guzzlephp.org/en/latest/request-options.html#verify
    CertFile: '',                       // [optional] path to client public key.  if set, requires KeyFile also be set
    KeyFile: '',                        // [optional] path to client private key.  if set, requires CertFile also be set

    // php specific options
    JSONEncodeOpts: JSON_UNESCAPED_SLASHES,
    JSONDecodeMaxDepth: 512,
    JSONDecodeOpts: 0,
);
```

#### Configuration Note:

[](#configuration-note)

By default, this client will attempt to locate a series of environment variables to describe much of the above configuration properties. See [here](./src/Config.php) for that list, and see [here](./src/Consul.php) for a list of the env var names.

For more advanced client configuration, such as proxy configuration, you must construct your own GuzzleHttp client prior to constructing a PHPConsulAPI Config object.

As an example:

```
$proxyClient = new \GuzzleHttp\Client(['proxy' => 'whatever proxy you want']);
$config = new \DCarbone\PHPConsulAPI\Config(
    HttpClient: $proxyClient,
    Address: 'address of server',
);
```

When constructing your client, if you are using the `GuzzleHttp\Client` object directly or derivative thereof, you may pass any option listed in the [Guzzle Request Options](http://docs.guzzlephp.org/en/latest/request-options.html).

Consul
------

[](#consul)

Next, construct a [Consul](./src/Consul.php) object:

```
$consul = new \DCarbone\PHPConsulAPI\Consul($config);
```

*NOTE*: If you do not create your own config object, [Consul](./src/Consul.php) will create it's own using [Config::newDefaultConfig()](./src/Config.php) and attempt to locate a suitable HTTP Client.

Once constructed, you interact with each Consul API via it's corresponding Client class:

```
$kvResp = $consul->KV->Keys();
if (null !== $kvResp->Err) {
    die($kvResp->Err);
}

var_dump($kvResp->Value);
```

...as an example.

Current Clients
---------------

[](#current-clients)

- [ACL](./src/ACL/ACLClient.php)
- [Agent](./src/Agent/AgentClient.php)
- [Catalog](./src/Catalog/CatalogClient.php)
- [Coordinate](./src/Coordinate/CoordinateClient.php)
- [Event](./src/Event/EventClient.php)
- [Health](./src/Health/HealthClient.php)
- [KV](./src/KV/KVClient.php)
- [Operator](./src/Operator/OperatorClient.php)
- [Session](./src/Session/SessionClient.php)
- [Status](./src/Status/StatusClient.php)

More will be added as time goes on!

Tests
-----

[](#tests)

The testing suite is still in it's infancy, however it is being tested directly against an actual Consul agent. They will be back-filled as time allows. Future plans are to set up a simple cluster to provide a more real-world testing scenario.

###  Health Score

61

—

FairBetter than 99% of packages

Maintenance93

Actively maintained with recent releases

Popularity24

Limited adoption so far

Community23

Small or concentrated contributor base

Maturity89

Battle-tested with a long release history

 Bus Factor1

Top contributor holds 96.6% 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 ~69 days

Recently: every ~223 days

Total

54

Last Release

23d ago

Major Versions

0.6.x-dev → v1.0.02021-02-10

v1.1.7 → v2.0.02024-02-11

v2.0.2 → v3.0.0-rc12026-07-05

PHP version history (8 changes)0.1.0PHP >=5.4.0

0.3.0PHP >=5.6.0

0.6.1.1PHP ^5.6 || ^7.0

v1.0.0PHP >=7.4

v1.1.0PHP 7.4.\* || 8.\*

v2.0.0PHP 8.\*

v2.0.2PHP ^8.1

v3.0.0-rc1PHP ^8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/385c0c0eae1b51f1e81ee464ff6bfb3cce32589ac252ca68cc3a8aec2e3ada14?d=identicon)[dcarbone](/maintainers/dcarbone)

---

Top Contributors

[![dcarbone](https://avatars.githubusercontent.com/u/1392439?v=4)](https://github.com/dcarbone "dcarbone (562 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (10 commits)")[![slt](https://avatars.githubusercontent.com/u/2295572?v=4)](https://github.com/slt "slt (2 commits)")[![kai890707](https://avatars.githubusercontent.com/u/62149120?v=4)](https://github.com/kai890707 "kai890707 (1 commits)")[![Perovmpr](https://avatars.githubusercontent.com/u/23420698?v=4)](https://github.com/Perovmpr "Perovmpr (1 commits)")[![sactor](https://avatars.githubusercontent.com/u/598282?v=4)](https://github.com/sactor "sactor (1 commits)")[![urosgruber](https://avatars.githubusercontent.com/u/590455?v=4)](https://github.com/urosgruber "urosgruber (1 commits)")[![cjones-vultr](https://avatars.githubusercontent.com/u/184550036?v=4)](https://github.com/cjones-vultr "cjones-vultr (1 commits)")[![wiggels](https://avatars.githubusercontent.com/u/16748278?v=4)](https://github.com/wiggels "wiggels (1 commits)")[![dmitriyGarden](https://avatars.githubusercontent.com/u/13615330?v=4)](https://github.com/dmitriyGarden "dmitriyGarden (1 commits)")[![fsotsk](https://avatars.githubusercontent.com/u/7643673?v=4)](https://github.com/fsotsk "fsotsk (1 commits)")

---

Tags

consulconsul-apiphpphp-clientconsulconsul-apiphp-consul-api

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/dcarbone-simple-consul-php/health.svg)

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

###  Alternatives

[aws/aws-sdk-php

AWS SDK for PHP - Use Amazon Web Services in your PHP project

6.2k555.0M2.8k](/packages/aws-aws-sdk-php)[eslazarev/wildberries-sdk

Wildberries OpenAPI clients (generated).

353.6k](/packages/eslazarev-wildberries-sdk)[spatie/crawler

Crawl all internal links found on a website

2.8k19.3M74](/packages/spatie-crawler)[dcarbone/php-consul-api

PHP client for the Consul HTTP API

79411.2k10](/packages/dcarbone-php-consul-api)[guzzlehttp/guzzle-services

Provides an implementation of the Guzzle Command library that uses Guzzle service descriptions to describe web services, serialize requests, and parse responses into easy to use model structures.

25511.2M199](/packages/guzzlehttp-guzzle-services)[drupal/core

Drupal is an open source content management platform powering millions of websites and applications.

19467.3M1.9k](/packages/drupal-core)

PHPackages © 2026

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