haveapi/client

A client for HaveAPI based APIs

haveapi-client-php

haveapi-client-php is a PHP client for HaveAPI based APIs., _(*1)

Requirements

• PHP >= 7.4
• Httpful

Installation

haveapi-client-php can be installed with composer, add haveapi/client to your composer.json:, _(*2)

{
    "require": {
        "haveapi/client": "*"
    }
}

You can also clone this repository and use a PSR-4 compatible autoloader, or include bootstrap.php, which loads all necessary classes. When using the repository, you have to install Httpful yourself., _(*3)

Usage

First check out the API documentation, see how it works and what resources/actions are available., _(*4)

Create a client instance:, _(*5)

$api = new \HaveAPI\Client("http://your.api.tld");

Authenticate with HTTP basic:, _(*6)

$api->authenticate('basic', ['user' => 'yourname', 'password' => 'password']);

Authenticate with token:, _(*7)

$api->authenticate('token', ['user' => 'yourname', 'password' => 'password']);

When using the token authentication, it is usually necessary to save the token for later use:, _(*8)

$token = $api->getAuthenticationProvider()->getToken();

Next time, authenticate with the previously received token:, _(*9)

$api->authenticate('token', ['token' => $token]);

Access resources and actions as array indexes

$api['vps']['index']->call();
$api['vps']['show']->call(101);

or, _(*10)

$api['vps.index']->call();
$api['vps.show']->call(101);

Access resources and actions as properties/methods

$api->vps->list();

Arguments can be supplied to resources and/or to the action., _(*11)

$api->vps->find(101);
$api->vps->ip_address->delete(101, 10);

$api->vps(101)->find();
$api->vps(101)->ip_address(10)->delete();
$api->vps(101)->ip_address->delete(10);

Parameters

Parameters are given as an array to action. It is the last argument given to action. Object IDs must be in front of it., _(*12)

$api->vps->create([
    'hostname' => 'myhostname',
    'template' => 1
]);

$api->vps->ip_address->create(101, ['version' => 4]);
$api->vps(101)->ip_address->create(['version' => 4]);

Object-like behaviour

Fetch existing resource:, _(*13)

$vps = $api->vps->find(101);
echo $vps->id . "<br>";
echo $vps->hostname . "<br>";
$vps->hostname = 'gotcha';
$vps->save();

Create a new instance:, _(*14)

$vps = $api->vps->newInstance();
$vps->hostname = 'new vps';
$vps->save();
echo $vps->id . "<br>";

List of resources:, _(*15)

$vpses = $api->vps->list();

foreach($vpses as $vps) {
    echo $vps->id ." = ". $vps->hostname ."<br>";
}

Response

If the action does not return object or object list, \HaveAPI\Client\Response class is returned instead., _(*16)

$vps = $api->vps->find(101);
$response = $vps->custom_action();

print_r($response->getResponse());

Parameters can be accessed directly as:, _(*17)

echo $response['hostname'];

Error handling

If an action fails, exception \HaveAPI\Client\Exception\ActionFailed is thrown. Authentication errors result in exception \HaveAPI\Client\Exception\AuthenticationFailed., _(*18)

try {
    $api->vps->create();

} catch(\HaveAPI\Client\Exception\ActionFailed $e) {
    echo $e->getMessage();
    print_r($e->getErrors());
}

When trying to access a resource or an action that does not exist, \HaveAPI\Client\Exception\ObjectNotFound is thrown. Also, invoking an action without all necessary arguments (object IDs) results in \HaveAPI\Client\Exception\UnresolvedArguments exception., _(*19)

All exceptions thrown by the client are a subclass of \HaveAPI\Client\Exception\Base., _(*20)

Documentation

https://projects.vpsfree.cz/haveapi-client-php/ref/, _(*21)

License

haveapi-client-php is released under the MIT license., _(*22)