Cyberfusion Cluster API client

Easily use the API of the clusters of the hosting company Cyberfusion. This package is build and tested on the 1.115 version of the API. This package is not created or maintained by Cyberfusion.

Requirements

This package requires PHP 7.4 or higher and uses Guzzle.

Installation

This package can be used in any PHP project or with any framework.

You can install the package via composer:

composer require vdhicts/cyberfusion-cluster-api-client

Usage

This package is just an easy client for using the Cyberfusion Cluster API. Please refer to the API documentation for more information about the requests.

Getting started

use Vdhicts\Cyberfusion\ClusterApi\Client;
use Vdhicts\Cyberfusion\ClusterApi\Configuration;
use Vdhicts\Cyberfusion\ClusterApi\ClusterApi;

// Create the configuration with your username/password
$configuration = Configuration::withCredentials('username', 'password');

// Start the client once and authorize
$client = new Client($configuration);

// Initialize the API
$api = new ClusterApi($client);

// Perform the request
$result = $api->virtualHosts()->list();

// Access the virtual host models
$virtualHosts = $result->getData('virtualHosts');

Sandbox mode

To easily test your implementation, you can enable the sandbox mode. Changes won't be made to your cluster.

To enable the sandbox mode, use the third parameter of the configuration, or set it separately:

$configuration = Configuration::withCredentials('username', 'password', true);

Or

$configuration = (new Configuration())
    ->setUsername('username')
    ->setPassword('password')
    ->setSandbox(true);

Requests

The endpoint methods may ask for filters, models or id's. The method typehints will tell you which input is requested.

Models

The endpoint may request a model, most create and update requests do.

$unixUser = (new UnixUser())
    ->setUsername('foo')
    ->setPassword('bar')
    ->setDefaultPhpVersion('7.4')
    ->setClusterId(1);

$result = $api
    ->unixUsers
    ->create($unixUser);

When models need to be provided, the required properties will be checked before executing the request. A RequestException will be thrown when properties are missing. See the message for more details.

Filtering data

Some endpoints require a ListFilter and return a list of models according to the filter. It's also possible to change the sort order.

A ListFilter can be initialized for a model, so it automatically validates if the provided fields are available for the model.

$listFilter = ListFilter::forModel(new Cluster());
$listFilter->addFilter('name', 'test');
$listFilter->addFilter('groups', 'test2');
$listFilter->addSort('name', ListFilter::SORT_DESC);

You are also able to initialize the ListFilter manually, but then no validation will be used for the fields.

Manually make requests

When you want to use the API directly, you can use the request() method on the Client. This method needs a Request class. See the class itself for its options.

Responses

The endpoint methods throw exceptions when the request fails due to timeouts. When the API replies with HTTP protocol errors the Response class is still returned. You can check the success of the request with: $response->isSuccess(). The content of the response is automatically converted to the models.

Authentication

The API is authenticated with a username and password and returns an access token. This package takes care of the authentication for you. To get your credentials, you need to contact Cyberfusion.

$configuration = Configuration::withCredentials('username', 'password');

When you authenticate with username and password, this package will automatically retrieve the access token. The access token is valid for 30 minutes, so there's not really any need to store this. If you want to store the access token anyway, it's stored in the Configuration class and accessible with: $configuration->getAccessToken().

Manually authenticate

It's also an option to manually authenticate:

use Vdhicts\Cyberfusion\ClusterApi\Client;
use Vdhicts\Cyberfusion\ClusterApi\ClusterApi;
use Vdhicts\Cyberfusion\ClusterApi\Configuration;
use Vdhicts\Cyberfusion\ClusterApi\Models\Login;

// Initialize the configuration without any credentials or access token
$configuration = new Configuration();

// Start the client with manual authentication
$client = new Client($configuration, true);

// Initialize the API
$api = new ClusterApi($client);

// Create the request
$login = (new Login())
    ->setUsername('username')
    ->setPassword('password');

// Perform the request
$response = $api
    ->authentication()
    ->login($login);

// Store the access token in the configuration
if ($response->isSuccess()) {
    $configuration->setAccessToken($response->getData('access_token'));
}

Enums

Some models have properties that should contain certain values. These values can be found in the enum classes and are there just for reference.

Exceptions

When something goes wrong, the client will throw an exception which extends the ClusterApiException. If you want to catch exceptions from this package, that's the one you should catch. All exceptions have a code, these codes can be found in the ClusterApiException class.

Deployment

Change to most of the objects in the cluster API require a deployment of the cluster. See Cluster Deployment for more information.

This package keeps track of the affected clusters. The deploy method on the client will automatically deploy all affected clusters for you:

$clusterDeployments = $client->deploy();

The result will be an array of Deployment objects (or an empty array who no clusters are affected) which enables you to check if the cluster is properly deployed:

foreach ($clusterDeployments as $clusterDeployment) {
    $success = $clusterDeployment->isSuccess();
    if (!$success) {
        // Do something with $clusterDeployment->getError();
    }
}

See the Deployment class for more options.

Automatic deployment

To make life easy, this package is also able to deploy any affected cluster automatically. This is opt-in behavior as you won't be able to access the result of the deployment. Enable this behavior in the configuration:

$configuration = new Configuration();
$configuration->setAutoDeploy(); // Enable the auto deployment of affected clusters

// Initialize the client
$client = new Client($configuration, true);

// Initialize the API
$api = new ClusterApi($client);

Manual deployment

When you disabled auto deployment and want to manually deploy, the commit endpoint can be called manually. You need to keep track of all affected clusters.

$api
    ->clusters()
    ->commit($clusterId);

Laravel

This package can be easily used in any Laravel application. I would suggest adding your username and password to your .env file:

CLUSTER_USERNAME=username
CLUSTER_PASSWORD=password

Next create a config file cluster.php in /config:

<?php

return [
    'username' => env('CLUSTER_USERNAME'),
    'password' => env('CLUSTER_PASSWORD'),
];

And use those files to build the configuration:

$configuration = Configuration::withCredentials(config('cluster.username'), config('cluster.password'));

In the future I might make a Laravel specific package which uses this package.

Tests

Unit tests are available in the tests folder. Run with:

composer test

When you want a code coverage report which will be generated in the build/report folder. Run with:

composer test-coverage

Contribution

Any contribution is welcome, but it should meet the PSR-2 standard and please create one pull request per feature/bug. In exchange, you will be credited as contributor on this page.

Security

If you discover any security related issues in this or other packages of Vdhicts, please email info@vdhicts.nl instead of using the issue tracker.

Support

This package isn't an official package from Cyberfusion, so they don't offer support for it. If you encounter a problem with this client or has a question about it, feel free to open an issue on GitHub.

License

This package is open-sourced software licensed under the MIT license.

About Vdhicts

Vdhicts is the name of my personal company for which I work as freelancer. Vdhicts develops and implements IT solutions for businesses and educational institutions.