README

A PHP client for the Consul HTTP API, modeled closely on the official Go client.

📖 Full documentation lives in the wiki.

Requirements

• PHP 8.2+ with ext-json
• guzzlehttp/guzzle ^7.4 (default HTTP client; any GuzzleHttp\ClientInterface works)
• brick/math ^1.0 (for uint64 values)
• dcarbone/gotime ^v2.0 (for Go-style durations)

Installation

composer require dcarbone/php-consul-api:^v3.1

Quick Start

use DCarbone\PHPConsulAPI\Config;
use DCarbone\PHPConsulAPI\Consul;
use DCarbone\PHPConsulAPI\KV\KVPair;

// With no arguments, configuration is read from the standard CONSUL_* environment variables,
// falling back to http://localhost:8500.
$consul = new Consul();

// ...or configure it explicitly.
$consul = new Consul(config: new Config(
    Address: 'consul.example.com:8500',
    Token: 'my-acl-token',
));

$err = $consul->KV->Put(p: new KVPair(Key: 'app/config/db', Value: 'postgres://localhost'))->Err;
if (null !== $err) {
    throw new \RuntimeException((string)$err);
}

[$pair, $qm, $err] = $consul->KV->Get(key: 'app/config/db');
if (null !== $err) {
    throw new \RuntimeException((string)$err);
}

echo $pair?->Value;    // "postgres://localhost" ($pair is null if the key does not exist)
echo $qm->LastIndex;   // index to use for blocking queries

Configuration

Config mirrors the Go client's api.Config, and new Consul(config: $config) applies the same defaults and precedence as Go's api.NewClient. Every parameter is optional.

Boolean env vars are parsed like Go's strconv.ParseBool (1, t, T, TRUE, true, True and their false equivalents); empty env vars are treated as unset.

For proxies, custom timeouts, middleware, etc., construct your own Guzzle client and pass it as HttpClient. See Configuration for address parsing, token precedence, TLS and other details.

Differences from the Go client

Configuration matches the Go client's api.NewClient() except:

• There is no Transport or nested TLSConfig. TLS fields live directly on Config, and in-memory PEM (CAPem, CertPEM, KeyPEM) is not supported.
• TLSServerName is stored but not applied, because Guzzle has no SNI override.
• TLS, basic auth and timeout are applied per request, so they also apply to a custom HttpClient. Go ignores TLSConfig when you supply your own client.
• unix:// addresses require ext-curl, and requests are sent with Host: localhost.

Other differences are covered under Working with Responses, Clients and Models. For the full list, including Go features not yet implemented (Connect, Snapshot, Lock/Semaphore, etc.), see Differences from Go.

Working with Responses

Every API call returns a response object. Responses can be destructured like the multiple return values of the Go client, or used via properties and getters:

// Read endpoints: [value, QueryMeta, error]
[$services, $qm, $err] = $consul->Catalog->Services();

// Write endpoints with a value: [value, WriteMeta, error]
[$sessionID, $wm, $err] = $consul->Session->Create(sessionEntry: $entry);

// Write endpoints without a value: [WriteMeta, error]
[$wm, $err] = $consul->KV->Delete(key: 'app/config/db');

// Some endpoints return no metadata: [value, error]
[$leader, $err] = $consul->Status->Leader();

// Object form
$resp = $consul->KV->Get(key: 'app/config/db');
$resp->getValue(); $resp->getQueryMeta(); $resp->getErr();

A few Agent methods return only null|Error. The exact shape of each method is documented on its client's wiki page.

Errors are never thrown for transport or API failures. They are returned as DCarbone\PHPConsulAPI\PHPLib\Error instances, which can be cast to a string.

Query and write options

Each method accepts an optional QueryOptions or WriteOptions argument to override the datacenter, token, consistency mode, and so on per request. Blocking queries work the same as in Go:

use DCarbone\PHPConsulAPI\QueryOptions;

[$pair, $qm, $err] = $consul->KV->Get(key: 'app/config/db');
[$pair, $qm, $err] = $consul->KV->Get(
    key: 'app/config/db',
    opts: new QueryOptions(WaitIndex: $qm->LastIndex, WaitTime: '30s'),
);

Big Integers (uint64)

As of v3.1.0, every field that Consul defines as uint64 is a Brick\Math\BigInteger. This covers CreateIndex, ModifyIndex, LockIndex, KVPair::$Flags, QueryMeta::$LastIndex, QueryOptions::$WaitIndex, Raft indexes and terms, and the return value of EventClient::IDToIndex(). PHP's int is signed, so values above PHP_INT_MAX would otherwise overflow.

• Setting: constructors and setters accept a non-negative int, a numeric string, or a BigInteger. Strings are validated with BigInteger::parse(). Negative, non-integer, and out-of-range values throw \InvalidArgumentException.
• Reading: use the BigInteger API (isEqualTo(), toInt(), (string)) rather than PHP int operators.
• JSON: responses are decoded with JSON_BIGINT_AS_STRING. Use \DCarbone\PHPConsulAPI\PHPLib\encode_json() rather than json_encode() if you need BigInteger values written as JSON numbers.

$pair = new KVPair(Key: 'app/config', Flags: '18446744073709551615');

if ($pair->Flags->isEqualTo(42)) { /* ... */ }
$index = (string)$qm->LastIndex;

See Big Integers.

Clients

Each client is available on Consul both as a property ($consul->KV) and as a method ($consul->KV()).

Unlike the Go client, there are no separate *Opts method variants. Each method takes an optional trailing options argument instead.

Models

Models are plain PHP classes with public properties, getters and setters, and named constructor parameters:

use DCarbone\PHPConsulAPI\Agent\AgentServiceCheck;
use DCarbone\PHPConsulAPI\Agent\AgentServiceRegistration;

$err = $consul->Agent->ServiceRegister(service: new AgentServiceRegistration(
    ID: 'web-1',
    Name: 'web',
    Tags: ['v1'],
    Port: 8080,
    Check: new AgentServiceCheck(TTL: '30s', DeregisterCriticalServiceAfter: '1m'),
));

Duration fields accept Go duration strings ('30s'), integers (nanoseconds), \DateInterval, or DCarbone\Go\Time\Duration. They are stored as Time\Duration.

Constructing models from an associative array (new KVPair(data: [...])) is deprecated. Use named parameters, or Model::jsonUnserialize($decoded) to hydrate from decoded JSON.

Version Compatibility

v3.x requires PHP 8.2+.

The library is tested against the latest Consul release. Newer versions may work with older Consul agents in a limited capacity, but backwards-compatibility issues with older agents will not be addressed.

Upgrading to v3

1. FakeMap, FakeSlice, ReadableDuration and the Transcoding helpers have been removed. Map-like fields are now associative arrays.
2. All models, including Config, use named constructor parameters. Array construction of models is deprecated, and Config can no longer be constructed from an array.
3. (v3.1.0) uint64 fields are Brick\Math\BigInteger. See Big Integers (uint64).
4. (v3.1.0) dcarbone/gotime has been upgraded to v2.
5. (next release) TLS certificates are now verified by default, CAFile is honored, and CONSUL_HTTP_SSL_VERIFY=false disables verification, matching the Go client. Previously, verification was disabled unless InsecureSkipVerify was true.
6. (next release) HttpAuth / CONSUL_HTTP_AUTH credentials are now sent as HTTP basic auth on every request. Previously they were parsed but never sent.
7. (next release) Config now follows Go's api.NewClient exactly: the default address is localhost:8500, Address may carry a http://, https:// or unix:// scheme and a path prefix, TokenFile follows Go's token precedence, boolean env vars use Go ParseBool semantics (yes/no/on/off are no longer accepted), and Partition, PathPrefix, CAPath and TLSServerName were added.

See Upgrading for details.

Development

composer install

# unit tests only
./vendor/bin/phpunit -c phpunit.xml --testsuite unit

# full suite; integration tests start and stop a local `consul` agent automatically,
# so the `consul` binary must be on your PATH
./vendor/bin/phpunit -c phpunit.xml

# static analysis and refactoring tools are installed separately under tools/
composer install --working-dir tools/rector
composer install --working-dir tools/phpstan
composer install --working-dir tools/psalm
composer rector
composer phpstan
composer psalm

See Development.

License

Apache-2.0