Skip to content

Configuration

Daniel Carbone edited this page Nov 6, 2026 · 3 revisions

Configuration

DCarbone\PHPConsulAPI\Config mirrors the Go client's api.Config. Every constructor parameter is optional and has a matching getter and setter (getAddress() / setAddress(), and so on).

use DCarbone\PHPConsulAPI\Config;
use DCarbone\PHPConsulAPI\Consul;

$consul = new Consul(config: new Config(
    Address: 'consul.example.com:8501',
    Scheme: 'https',
    Datacenter: 'dc1',
    Token: 'my-acl-token',
    CAFile: '/etc/consul/ca.pem',
    WaitTime: '5m',
));

Parameters

Parameter Type Default / Env var Description
Address string CONSUL_HTTP_ADDR, else 127.0.0.1:8500 Agent address (host:port)
Scheme bool|string CONSUL_HTTP_SSL (true → https), else http http/https; true/'1' → https, false/'0' → http
Datacenter string '' (agent's datacenter) Default datacenter, sent as ?dc=
Namespace string '' Default namespace, sent as ?ns= (Enterprise)
HttpAuth null|string|HttpAuth CONSUL_HTTP_AUTH HTTP basic auth, user:pass or new HttpAuth(username: ..., password: ...)
WaitTime duration none Default max wait for blocking queries
Token string CONSUL_HTTP_TOKEN ACL token, sent as X-Consul-Token
TokenFile string CONSUL_HTTP_TOKEN_FILE File containing the ACL token
CAFile string CONSUL_CACERT CA bundle used to verify the server certificate
CertFile string CONSUL_CLIENT_CERT Client certificate for mTLS (requires KeyFile)
KeyFile string CONSUL_CLIENT_KEY Client key for mTLS (requires CertFile)
InsecureSkipVerify null|bool CONSUL_HTTP_SSL_VERIFY (false → skip), else false Disable TLS certificate verification
HttpClient GuzzleHttp\ClientInterface new GuzzleHttp\Client() HTTP client used for all requests
JSONEncodeOpts int JSON_UNESCAPED_SLASHES Flags passed to json_encode
JSONDecodeMaxDepth int 512 Max depth passed to json_decode
JSONDecodeOpts int 0 Flags passed to json_decode (JSON_BIGINT_AS_STRING is always added)

"duration" means any value accepted by Time::Duration(): a Go duration string ('30s'), an int of nanoseconds, a \DateInterval, or a DCarbone\Go\Time\Duration. See Durations and Time.

Passing CertFile without KeyFile (or the reverse) throws \InvalidArgumentException.

Environment variables

When a parameter is not given, Config reads the same environment variables as the Consul CLI and Go client:

Variable Parameter
CONSUL_HTTP_ADDR Address
CONSUL_HTTP_TOKEN Token
CONSUL_HTTP_TOKEN_FILE TokenFile
CONSUL_HTTP_AUTH HttpAuth
CONSUL_HTTP_SSL Scheme
CONSUL_HTTP_SSL_VERIFY InsecureSkipVerify (inverted)
CONSUL_CACERT CAFile
CONSUL_CLIENT_CERT CertFile
CONSUL_CLIENT_KEY KeyFile

Env var names are also available as constants on Consul (e.g. Consul::HTTPAddrEnvName).

How Consul merges config

new Consul(config: $config) starts from a default, environment-derived config and overlays the non-empty values of the config you pass. In practice:

  • Any value you set explicitly wins over the environment.
  • Empty values ('', null) fall back to the environment or the default.
  • InsecureSkipVerify is only overlaid when it is true. As with the Go client, passing InsecureSkipVerify: false does not re-enable verification if CONSUL_HTTP_SSL_VERIFY=false is set in the environment.

Authentication

ACL token

Set Token, or TokenFile to read it from disk. When TokenFile is set, the file is read when the Consul instance is created and its contents are used if Token is empty. An unreadable file throws \RuntimeException.

The token can be overridden per request with QueryOptions(Token: ...) / WriteOptions(Token: ...).

HTTP basic auth

If Consul is behind a proxy that requires basic auth:

use DCarbone\PHPConsulAPI\HttpAuth;

new Config(HttpAuth: 'user:pass');
new Config(HttpAuth: new HttpAuth(username: 'user', password: 'pass'));

The credentials are sent on every request.

TLS

  • Server certificates are verified by default, using the system CA bundle.
  • CAFile replaces the system bundle with your own CA.
  • InsecureSkipVerify: true (or CONSUL_HTTP_SSL_VERIFY=false) disables verification entirely, even if CAFile is set.
  • CertFile + KeyFile present a client certificate (for verify_incoming agents).
$config = new Config(
    Address: 'consul.service:8501',
    Scheme: 'https',
    CAFile: '/etc/consul/ca.pem',
    CertFile: '/etc/consul/client.pem',
    KeyFile: '/etc/consul/client-key.pem',
);

Before the next release, verification was disabled unless InsecureSkipVerify was true. See Upgrading.

Custom HTTP client

Any GuzzleHttp\ClientInterface can be used. This is how to configure proxies, connection timeouts, retries, logging middleware, and so on:

use GuzzleHttp\Client;
use GuzzleHttp\HandlerStack;
use GuzzleHttp\Middleware;

$stack = HandlerStack::create();
$stack->push(Middleware::log($logger, new \GuzzleHttp\MessageFormatter()));

$config = new Config(HttpClient: new Client([
    'handler'         => $stack,
    'connect_timeout' => 2,
    'proxy'           => 'http://proxy.internal:3128',
]));

The library always sends http_errors => false and decode_content => false, and sets verify, cert, ssl_key, auth, and timeout per request from Config and the request options. Don't rely on setting those on the client.

A per-request timeout is set with QueryOptions(Timeout: '10s') / WriteOptions(Timeout: '10s'). See Query and Write Options.

JSON options

JSONEncodeOpts, JSONDecodeMaxDepth, and JSONDecodeOpts control how request and response bodies are encoded and decoded. Responses are always decoded with JSON_BIGINT_AS_STRING so that uint64 values are not truncated. See Big Integers.

Default wait time

WaitTime sets a default ?wait= on every request. Consul only uses it for blocking queries (requests that also carry a WaitIndex or WaitHash). It can be overridden per request with QueryOptions(WaitTime: ...).

Clone this wiki locally