README

PHP client for the Consul HTTP API

This library is loosely based upon the official GO client.

PHP Compatibility

• v3.x requires PHP 8.2+.

Version Compatibility

Newer 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

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<string,mixed>); some JSON object inputs may still be accepted as \stdClass at setter boundaries.

Composer

This lib is designed to be used with Composer

Require Entry:

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

Configuration

First, construct a Config. This class is modeled quite closely after the Config Struct present in the Consul API Subpackage.

Default Configuration

If you have defined some of the Consul Environment Variables on your hosts then it would probably be easiest to simply execute the following:

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

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:

By default, this client will attempt to locate a series of environment variables to describe much of the above configuration properties. See here for that list, and see here 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.

Consul

Next, construct a Consul object:

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

NOTE: If you do not create your own config object, Consul will create it's own using Config::newDefaultConfig() 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

• ACL
• Agent
• Catalog
• Coordinate
• Event
• Health
• KV
• Operator
• Session
• Status

More will be added as time goes on!

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.