This is an API for HetrixTools V2 API, aiming to make dealing with creating/updating/deleting/fetching Uptime and RBL Monitors easier and more fluent.
- PHP 7.1 or higher
Via composer
$ composer require cmdrsharp/hetrixtools-api
Include the factory
or repository
that you need (either Uptime or Blacklist), then spawn up an instance of the class, supplying your API Key as the only argument. Finally, build out your request.
A full list of available methods for both the factories and repositories are available further down in this readme.
// Example Uptime Monitor creation (adding a ping monitor to 8.8.8.8)
use CmdrSharp\HetrixtoolsApi\Uptime\Factory as HetrixTools;
$monitor = new HetrixTools('myApiKey');
try {
$result = $monitor->type('service')
->name('Greatest Monitor')
->target('8.8.8.8')
->timeout(10)
->frequency(1)
->failsBeforeAlert(1)
->public(false)
->showTarget(false)
->locations([
'dal' => true,
'msw' => true,
'nyc' => true
])->create();
} catch(\Exception $e) {
print($e->getMessage());
}
// Example Blacklist Monitor creation (adding a monitor to 192.168.0.0/24)
use CmdrSharp\HetrixtoolsApi\Blacklist\Factory as HetrixTools;
$monitor = new HetrixTools('myApiKey');
try {
$result = $monitor->target('192.168.0.0/24')
->label('Blacklist Monitor 1')
->contact(1)
->create();
} catch(\Exception $e) {
print($e->getMessage());
}
// Example Listing Uptime Monitors
use CmdrSharp\HetrixtoolsApi\Uptime\Repository as HetrixTools;
$instance = new HetrixTools('myApiKey');
try {
$result = $instance->listUptimeMonitors(); // Fetches 100 results
$result = $instance->listUptimeMonitors(0, 50); // Page 0, 50 results per page.
} catch(\Exception $e) {
print($e->getMessage());
}
// Example Blacklist Report
use CmdrSharp\HetrixtoolsApi\Blacklist\Repository as HetrixTools;
$instance = new HetrixTools('myApiKey');
try {
$result = $instance->blacklistReport('8.8.8.8');
$result = $instance->blacklistReport('8.8.8.8', '2018-03-29');
} catch(\Exception $e) {
print($e->getMessage());
}
The client returns a normal PSR ResponseInterface. This means you interact with the response as you would with any Guzzle response.
$result->getStatusCode(); // 200
$result->getBody(); // {"status":"SUCCESS","monitor_id":"exampleMonitorId","action":"added"}
Now that we have created a monitor, we may want to modify it. This is almost identical to the regular request. For Uptime Monitors, the ID field must be supplied. For Blacklist Monitors, the Target field is required. Apart from that, include what you want to change.
// Example for modifying Uptime Monitors
try {
// Changing the target, category and locations
$result = $monitor->id('exampleMonitorId')
->target('8.8.4.4')
->category('My awesome monitor')
->locations([
'dal' => true,
'msw' => true,
'nyc' => true,
'mos' => true
])->patch();
// Changing the name only.
$result = $monitor->id('exampleMonitorId')
->name('New awesome monitor')
->patch();
} catch(\Exception $e) {
print($e->getMessage());
}
// Example for modifying Blacklist Monitors
try {
$result = $monitor->target('192.168.0.0/24')
->label('Blacklist Monitor 113')
->contact(5)
->patch();
} catch(\Exception $e) {
print($e->getMessage());
}
The CREATE
, PATCH
and DELETE
methods should always be at the end of the procedure call. All methods can be chained together. Some parameters are optional, and which ones are required will differ depending on what type of monitor you're creating. For a full overview of this, review the HetrixTools API Documentation.
// Common Methods (for both Blacklist and Uptime)
create();
patch();
delete();
target(String $target);
listMonitors(?int $page = null, ?int $per_page = null);
listContacts();
// FACTORY: Uptime Monitoring Methods
id(String $id);
type(String $type);
name(String $name);
timeout(int $timeout);
frequency(int $frequency);
failsBeforeAlert(int $fails);
failedLocations(int $failed);
contactList(int $contactList);
category(String $category);
alertAfter(int $time);
repeatTimes(int $times);
repeatEvery(int $every);
public(bool $public);
showTarget(bool $show);
verify_ssl_certificate(bool $verify);
verify_ssl_host(bool $verify);
locations(array $locations);
keyword(String $keyword);
maxRedirects(int $redirects);
port(int $port);
checkAuth(bool $check);
smtpUser(String $user);
smtpPass(String $pass);
// REPOSITORY: Uptime Monitoring Methods
status();
uptimeReport(String $id);
// FACTORY: Blacklist Monitoring Methods
label(String $label);
contact(int $contact);
// REPOSITORY: Blacklist Monitoring Methods
blacklistReport(String $target, ?String $date = null);
manualCheck(String $target);
Upon receiving input that fails validation, a InvalidArgumentException
will be thrown. Upon receiving a response from the API which translates to an error, an ErrorException
is thrown.
It is therefore recommended to run the operations within a try/catch statement.
The included tests only verify that expected input/output to the interface work as intended. No tests are run toward the HetrixTools API itself, as this is currently not possible without making actual live changes.
This package follows Explicit Versioning.
Many thanks to HetrixTools, a service I fully endorse and recommend everyone to use for their uptime and blacklist monitoring needs!