README.md

Consul.io PHP library

This is a PHP library for the consul.io application. Note that this is in development right now. Feel free to open PRs.

Installation

1. Require the package via composer

$ composer require "br/consul-php"

2. Instantiate the library:

Depending on which part of the library you want to use, instantiate the correct Client:

$client = new \BR\Consul\Agent('http://localhost:8500'); // to issue commands to the local agent
$client = new \BR\Consul\KeyValueStore('http://localhost:8500'); // to access the Key Value Store

Usage

1. Key/Value Store

Use the getValue(), setValue() and deleteValue() functions of the client. Example:

$client->setValue('myKey', 'myValue');
$client->setValue('myKey', 'myValue', 'datacenter-east'); // Set the value in the datacenter-east datacenter

$client->getValue('myKey');
$client->getValue('myKey', 'datacenter-east'); // Get the value from the datacenter-east datacenter

$client->deleteValue('myKey');
$client->deleteValue('myKey', 'datacenter-east'); // Delete the value from the datacenter-east datacenter

2. Agent

2.1 Registering a service with the agent

In order to register a service, you have to create a BR\Consul\Model\Service object, and pass it to the Client::registerService() function. Example:

$service = new \BR\Consul\Model\Service();
$service->setName('postgres');
$service->setId('postgres-1');
$service->setTags(['master']);
$service->setPort(5432);

$success = $client->registerService($service);

2.2 Retrieving a list of all services registered with the agent

You can retrieve a list of services that are registered with the agent. Example:

$services = $service->getServices();
var_dump(count($services));

/** $srv \BR\Consul\Model\Service */
foreach ($services as $srv) {
    echo $srv->getName()
}

2.3 Removing a service from the agent

$client->deregisterService('postgres-1');
// alternatively
$client->removeService($service);

3. Catalog

3.1. Get a list of datacenters

$datacenters = $client->getDatacenters();
var_dump(count($datacenters));

/** $datacenter \BR\Consul\Model\Datacenter */
foreach ($datacenters as $datacenter) {
    echo $datacenter->getName();
}

Tests

Run the unit and functional tests by running phpunit in the root of the repository.

To run consul, use:

$ ./consul agent -data-dir . --bootstrap -server