Agent

Agent

$consul->Agent wraps Consul's Agent API. It talks to the local agent you are connected to.

Note: Many agent methods return a bare null|Error rather than a response object. Others return [$value, $err] with no meta. Check the table below.

Registering a service

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

$err = $consul->Agent->ServiceRegister(service: new AgentServiceRegistration(
    ID: 'web-1',
    Name: 'web',
    Tags: ['v1', 'primary'],
    Port: 8080,
    Address: '127.0.0.1',
    Meta: ['version' => '1.2.3'],
    Check: new AgentServiceCheck(TTL: '30s', DeregisterCriticalServiceAfter: '1m'),
));
if (null !== $err) {
    throw new RuntimeException((string)$err);
}

// Heartbeat the TTL check.  Service checks are named "service:<id>".
$err = $consul->Agent->PassTTL(checkID: 'service:web-1', note: 'all good');

// Remove it again.
$err = $consul->Agent->ServiceDeregister(serviceID: 'web-1');

AgentServiceCheck's Interval, Timeout, TTL and DeregisterCriticalServiceAfter are strings (e.g. '30s'), as Consul expects. To attach several checks, pass Checks: new AgentServiceChecks(Checks: [new AgentServiceCheck(...), ...]).

Reading local state

[$services, $err] = $consul->Agent->Services();      // array<string, AgentService>, keyed by service ID
[$svc, $err]      = $consul->Agent->Service(serviceID: 'web-1');
echo "{$svc->Service}:{$svc->Port}";

[$filtered, $err] = $consul->Agent->ServicesWithFilter(filter: 'Service == "web"');

[$checks, $err]  = $consul->Agent->Checks();          // array<string, AgentCheck>, keyed by check ID
[$members, $err] = $consul->Agent->Members();         // AgentMember[]
[$self, $err]    = $consul->Agent->Self();            // array<string, mixed>
[$name, $err]    = $consul->Agent->NodeName();

Standalone checks

use DCarbone\PHPConsulAPI\Agent\AgentCheckRegistration;
use DCarbone\PHPConsulAPI\Consul;

$err = $consul->Agent->CheckRegister(check: new AgentCheckRegistration(ID: 'disk', Name: 'Disk space', TTL: '1m'));
$err = $consul->Agent->UpdateTTL(checkID: 'disk', output: '80% free', status: Consul::HealthPassing);
$err = $consul->Agent->CheckDeregister(checkID: 'disk');

Maintenance mode

$err = $consul->Agent->EnableNodeMaintenance(reason: 'patching');
$err = $consul->Agent->DisableNodeMaintenance();

$err = $consul->Agent->EnableServiceMaintenance(serviceID: 'web-1', reason: 'deploying');
$err = $consul->Agent->DisableServiceMaintenance(serviceID: 'web-1');

See Responses and Errors and Query and Write Options.