Upgrading

Upgrading

Next release

These changes are on main but haven't been released yet.

TLS certificates are verified by default

Previously, HTTPS certificate verification was disabled unless InsecureSkipVerify was true. It now matches the Go client:

• Certificates are verified by default.
• CAFile / CONSUL_CACERT is used as the CA bundle.
• InsecureSkipVerify: true or CONSUL_HTTP_SSL_VERIFY=false disables verification.

If you talk to Consul over HTTPS with a private CA, set CAFile. Otherwise requests will now fail with a certificate error.

Config matches Go's api.NewClient

Config and new Consul(config: ...) now follow the Go client exactly:

• The default address is localhost:8500 (was 127.0.0.1:8500).
• Address may include a http://, https:// or unix:// scheme and a path prefix (https://proxy/consul). Unknown schemes throw \InvalidArgumentException.
• TokenFile / CONSUL_HTTP_TOKEN_FILE follow Go's token precedence. See Configuration.
• CONSUL_HTTP_SSL and CONSUL_HTTP_SSL_VERIFY are parsed like Go's strconv.ParseBool. yes, no, on and off are no longer accepted, and empty values are treated as unset.
• Namespace is read from CONSUL_NAMESPACE.
• New parameters: Partition (CONSUL_PARTITION), PathPrefix, CAPath (CONSUL_CAPATH) and TLSServerName (CONSUL_TLS_SERVER_NAME).
• Config::merge() no longer modifies the config passed to it.

HTTP basic auth is sent

HttpAuth / CONSUL_HTTP_AUTH was parsed but never sent. It is now sent as HTTP basic auth on every request. If you set it but your Consul (or proxy) doesn't expect it, remove it.

Other fixes

• null lists in responses (e.g. "Tags": null) now hydrate as empty arrays, instead of causing a TypeError.
• Event\UserEvent::$Payload is base64-encoded and decoded correctly, so payloads round-trip through Event->Fire() and Event->List().
• PreparedQuery\ServiceQuery now sends NodeMeta / ServiceMeta as JSON objects (an empty array used to be sent as []). It also hydrates them with string keys, and handles null Tags / IgnoreCheckIDs.

v3.1.0

uint64 fields are BigInteger

Every field that Consul defines as uint64 is now a Brick\Math\BigInteger. This includes indexes, KVPair::$Flags, QueryMeta::$LastIndex, Raft indexes, and UserEvent::$LTime. Setters still accept int, but reads return objects:

// before
if ($qm->LastIndex > $last) { /* ... */ }
$flags = $pair->Flags + 1;

// after
if ($qm->LastIndex->isGreaterThan($last)) { /* ... */ }
$flags = $pair->Flags->plus(1);

See Big Integers.

gotime v2

dcarbone/gotime was upgraded to ^2.0. If you only pass duration strings or ints into the library, nothing changes. If you use gotime directly, review its release notes. See Durations and Time.

Other changes

• ServiceConfigEntry::$ProxyMode was renamed to $Mode to match the Go client (json:"Mode").
• Several wire-format fixes. Some fields are now sent with the JSON key Consul actually expects.

v2 → v3

v3 requires PHP 8.2+.

• FakeMap, FakeSlice, ReadableDuration, and the Transcoding helpers were removed. Map-like fields are plain associative arrays, and list fields are plain arrays.

• All models use typed public properties and named constructor parameters:

  // v2
  $pair = new KVPair(['Key' => 'foo', 'Value' => 'bar']);
  
  // v3
  $pair = new KVPair(Key: 'foo', Value: 'bar');

  Array construction (data:) still works on most models, but is deprecated. Use Model::jsonUnserialize() to hydrate from decoded JSON. See Models.

• Config can no longer be constructed from an array. Use named parameters, or Config::newDefaultConfig() / Config::merge(). See Configuration.

• Duration fields are DCarbone\Go\Time\Duration. Timestamps are DCarbone\Go\Time\Time.

• Enum-like fields (e.g. ProxyMode, MeshGatewayMode, IntentionAction) are PHP enums. Constructors and setters accept either the enum case or its string value.