friendsofphp / consul-php-sdk
SDK to talk with consul.io API
Installs: 90 288
Dependents: 4
Suggesters: 0
Security: 0
Stars: 316
Watchers: 18
Forks: 56
Open Issues: 0
Requires
- php: >=8.1
- psr/log: ^1|^2|^3
- symfony/http-client: ^5.4|^6.4|^7.0
Requires (Dev)
- symfony/phpunit-bridge: ^6.0|^7.0
README
Consul PHP SDK is a thin wrapper around the Consul HTTP API.
Compatibility
See previous version of README.md to find some version compatible with older version of symfony/http-client or guzzle
Installation
This library can be installed with composer:
composer require friendsofphp/consul-php-sdk
Supported services
- agent
- catalog
- health
- kv
- session
- txn
Usage
Instantiate a services, and start using it:
$kv = new Consul\Services\KV(); $kv->put('test/foo/bar', 'bazinga'); $kv->get('test/foo/bar', ['raw' => true]); $kv->delete('test/foo/bar');
A service exposes few methods mapped from the consul API:
All services methods follow the same convention:
$response = $service->method($mandatoryArgument, $someOptions);
- All API mandatory arguments are placed as first;
- All API optional arguments are directly mapped from
$someOptions
; - All methods return a
Consul\ConsulResponse
; - If the API responds with a 4xx response, a
Consul\Exception\ClientException
is thrown; - If the API responds with a 5xx response, a
Consul\Exception\ServeException
is thrown.
Cookbook
How to acquire an exclusive lock?
$session = new Consul\Services\Session(); $sessionId = $session->create()->json()['ID']; // Lock a key / value with the current session $lockAcquired = $kv->put('tests/session/a-lock', 'a value', ['acquire' => $sessionId])->json(); if (false === $lockAcquired) { $session->destroy($sessionId); echo "The lock is already acquire by another node.\n"; exit(1); } echo "Do you jobs here...."; sleep(5); echo "End\n"; $kv->delete('tests/session/a-lock'); $session->destroy($sessionId);
How to use MultiLockHandler?
$resources = ['resource1', 'resource2']; $multiLockHandler = new MultiLockHandler($resources, 60, new Session(), new KV(), 'my/lock/'); if ($multiLockHandler->lock()) { try { echo "Do you jobs here...."; } finally { $multiLockHandler->release(); } }
How to use MultiSemaphore?
$resources = [ new Resource('resource1', 2, 7), new Resource('resource2', 3, 6), new Resource('resource3', 1, 1), ]; $semaphore = new MultiSemaphore($resources, 60, new Session(), new KV(), 'my/semaphore'); if ($semaphore->acquire()) { try { echo "Do you jobs here...."; } finally { $semaphore->release(); } }
Some utilities
Consul\Helper\LockHandler
: Simple class that implement a distributed lockConsul\Helper\MultiLockHandler
: Simple class that implements a distributed lock for many resourcesConsul\Helper\MultiSemaphore
: Simple class that implements a distributed semaphore for many resources
Run the test suite
You need a consul agent running on localhost:8500
.
But you ca override this address:
export CONSUL_HTTP_ADDR=172.17.0.2:8500
If you don't want to install Consul locally you can use a docker container:
docker run -d --name=dev-consul -e CONSUL_BIND_INTERFACE=eth0 consul
Then, run the test suite
vendor/bin/simple-phpunit