Repository navigation
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',
));| 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.
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).
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. -
InsecureSkipVerifyis only overlaid when it istrue. As with the Go client, passingInsecureSkipVerify: falsedoes not re-enable verification ifCONSUL_HTTP_SSL_VERIFY=falseis set in the environment.
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: ...).
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.
- Server certificates are verified by default, using the system CA bundle.
-
CAFilereplaces the system bundle with your own CA. -
InsecureSkipVerify: true(orCONSUL_HTTP_SSL_VERIFY=false) disables verification entirely, even ifCAFileis set. -
CertFile+KeyFilepresent a client certificate (forverify_incomingagents).
$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
InsecureSkipVerifywastrue. See Upgrading.
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.
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.
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: ...).