Models

Models

Request and response bodies are represented by model classes, such as KV\KVPair, Agent\AgentServiceRegistration, and Health\ServiceEntry. Each one mirrors the struct of the same name in the Go client (github.com/hashicorp/consul/api), with the same field names.

Constructing

Every field is a constructor parameter with the same name. Use named arguments:

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

$reg = new AgentServiceRegistration(
    ID: 'web-1',
    Name: 'web',
    Tags: ['v1', 'primary'],
    Port: 8080,
    Address: '10.0.0.10',
    Meta: ['version' => '1.2.3'],
    Check: new AgentServiceCheck(HTTP: 'http://10.0.0.10:8080/health', Interval: '10s', Timeout: '2s'),
);

Parameters are typed, and are converted for you where it makes sense:

Field kind	Accepts	Stored as
uint64	non-negative int, numeric string, BigInteger	BigInteger
Duration	'30s', int ns, float ns, \DateInterval, Duration, null	Time\Duration
Time	Time\Time, null	null|Time\Time
Enum (e.g. ProxyMode)	the enum case, or its string value	the enum case
Lists	variadic setters (setTags(string ...$Tags))	array
Maps (e.g. Meta)	array<string,...>	array

See Big Integers and Durations and Time.

An enum string that isn't a valid case throws \ValueError:

use DCarbone\PHPConsulAPI\ConfigEntry\ProxyMode;
use DCarbone\PHPConsulAPI\ConfigEntry\ServiceConfigEntry;
use DCarbone\PHPConsulAPI\Consul;

new ServiceConfigEntry(Kind: Consul::ServiceDefaults, Name: 'web', Mode: 'transparent');
new ServiceConfigEntry(Kind: Consul::ServiceDefaults, Name: 'web', Mode: ProxyMode::Transparent);

Reading and writing fields

All fields are public properties, and each has a getter and a fluent setter:

$pair->Value;
$pair->getValue();
$pair->setValue(Value: 'new')->setFlags(Flags: 42);

Boolean getters use is ($qm->isKnownLeader()).

JSON

Models implement \JsonSerializable, so json_encode($model) produces the JSON that Consul expects. Most fields tagged omitempty in Go are omitted when empty.

To build a model from decoded JSON (for example, a cached response or a fixture):

use DCarbone\PHPConsulAPI\KV\KVPair;

$pair = KVPair::jsonUnserialize(json_decode($json, false, 512, JSON_BIGINT_AS_STRING));

Fields that the model doesn't know about, such as fields added in a newer Consul version, are kept as dynamic properties and written back out by jsonSerialize(). This means a read-modify-write round trip doesn't drop data.

Use encode_json() instead of json_encode() if you need BigInteger values written as JSON numbers. See Big Integers.

Deprecated: array construction

Older versions allowed new KVPair(['Key' => 'foo']). A data: array parameter is still accepted on most models, but it is deprecated and will be removed. Use named parameters or jsonUnserialize() instead.

Config entries

ConfigEntry\ConfigEntry is the interface implemented by all config entry models. Results from ConfigEntry->Get() / List() are decoded into the right class based on Kind:

Kind constant	Class
Consul::ServiceDefaults	ServiceConfigEntry
Consul::ProxyDefaults	ProxyConfigEntry
Consul::ServiceRouter	ServiceRouterConfigEntry
Consul::ServiceSplitter	ServiceSplitterConfigEntry
Consul::ServiceResolver	ServiceResolverConfigEntry
Consul::IngressGateway	IngressGatewayConfigEntry
Consul::TerminatingGateway	TerminatingGatewayConfigEntry
Consul::ServiceIntentions	ServiceIntentionsConfigEntry
Consul::MeshConfig	MeshConfigEntry
anything else	GenericConfigEntry

GenericConfigEntry keeps all fields as dynamic properties, so kinds without a dedicated class (e.g. exported-services, api-gateway, jwt-provider) still round-trip.

Consul::MakeConfigEntry(kind: ..., name: ...) creates an empty entry of the right class. It supports the kinds in the table above except MeshConfig, and throws \InvalidArgumentException for anything else.

See ConfigEntry.

Constants

DCarbone\PHPConsulAPI\Consul holds the constants from the Go client:

Group	Constants
Health states	HealthAny, HealthPassing, HealthWarning, HealthCritical, HealthMaint
Maintenance	NodeMaint, ServiceMaintPrefix
Segments	AllSegments
KV txn verbs	KVSet, KVDelete, KVDeleteCAS, KVDeleteTree, KVCAS, KVLock, KVUnlock, KVGet, KVGetOrEmpty, KVGetTree, KVCheckSession, KVCheckIndex, KVCheckNotExists (also the Txn\KVOp enum)
Session behavior	SessionBehaviorRelease, SessionBehaviorDelete
Member tags	MemberTagKeyACLMode, MemberTagKeyRole, MemberTagValueRoleServer, MemberTagKeySegment, ...
Config entry kinds	ServiceDefaults, ProxyDefaults, ServiceRouter, ServiceSplitter, ServiceResolver, IngressGateway, TerminatingGateway, ServiceIntentions, MeshConfig, ExportedServices, SamenessGroup, APIGateway, HTTPRoute, TCPRoute, InlineCertificate, FileSystemCertificate, JWTProvider, RateLimitIPConfig, ...
Envoy extensions	BuiltinAWSLambdaExtension, BuiltinExtAuthzExtension, BuiltinLuaExtension, BuiltinWasmExtension, ...
Env var names	HTTPAddrEnvName, HTTPTokenEnvName, ... (see Configuration)