cyberfusion/core-api-client

PHP client for the Cyberfusion Core API. Built upon the Saloon package and officially supported by Cyberfusion. The client is generated from the Core API's OpenAPI specification, which keeps it automatically in sync with the API.

Built for and tested on API version 1.268.0.

Requirements#

This package requires PHP 8.2 or higher. It uses Guzzle via Saloon and some specific Laravel components, but the Laravel framework itself is not required.

Installation#

You can install the package via composer:

composer require cyberfusion/core-api-client

Usage#

Getting started#

use Cyberfusion\CoreApi\CoreApiConnector;

$connector = new CoreApiConnector(
    username: 'username',
    password: 'password',
);

// List multiple resources
foreach ($connector->virtualHosts()->listVirtualHosts()->items() as $virtualHost) {
    echo $virtualHost->getDomain();
}

// Read a single resource
$virtualHost = $connector
    ->virtualHosts()
    ->readVirtualHost(1)
    ->dto();

Authentication#

Authenticate with your username and password. An AuthenticationException is thrown when authentication fails.

Requests#

DTOs are validated before sending. A ValidationException is thrown when the request data is invalid.

use Cyberfusion\CoreApi\CoreApiConnector;
use Cyberfusion\CoreApi\Models\MailDomainCreateRequest;

$connector = new CoreApiConnector(username: 'username', password: 'password');

$mailDomain = $connector
    ->mailDomains()
    ->createMailDomain(new MailDomainCreateRequest(
        domain: 'cyberfusion.io',
        unixUserId: 1,
        isLocal: true,
    ))
    ->dto();

Responses#

Get a single model#

$virtualHost = $connector->virtualHosts()->readVirtualHost(1)->dto();

List multiple models#

List responses are automatically paginated and returned as a lazy collection:

foreach ($connector->virtualHosts()->listVirtualHosts()->items() as $virtualHost) {
    echo $virtualHost->getDomain();
}

You can also work with the lazy collection directly:

$virtualHosts = $connector->virtualHosts()->listVirtualHosts()->collect();

Error Handling#

use Saloon\Exceptions\Request\RequestException;

try {
    $virtualHost = $connector->virtualHosts()->createVirtualHost(...)->dto();
} catch (RequestFailedException $exception) {
    echo $exception->getDetailMessage()->getDetail();
} catch (ValidationException $exception) {
    foreach ($exception->errors() as $error) {
        echo $error->getMsg();
    }
}

Filtering#

Use search request models to filter list results:

use Cyberfusion\CoreApi\Models\MailAliasesSearchRequest;

$filter = new MailAliasesSearchRequest();
$filter->setLocalPart('info');

$connector->mailAliases()->listMailAliases($filter);

Includes#

Request related resources to be included in the response:

$connector->mailAliases()->listMailAliases(includes: ['mail_domain']);

Middleware#

Saloon middleware#

$connector->middleware()->onRequest(function (PendingRequest $pendingRequest) { ... });
$connector->middleware()->onResponse(function (Response $response) { ... });

Guzzle middleware#

$connector->sender()->addMiddleware(/* your Guzzle middleware */);

For example, using the goedemiddag/request-response-log package to log all API requests:

use Goedemiddag\RequestResponseLog\RequestResponseLogger;

$connector->sender()->addMiddleware(
    RequestResponseLogger::middleware('cyberfusion')
);

Manual Requests#

For endpoints not yet implemented in the client, you can send manual requests:

use Cyberfusion\CoreApi\Support\ManualRequest;
use Saloon\Enums\Method;

$response = $connector->send(new ManualRequest(
    url: '/api/v1/health',
    method: Method::GET,
    data: [],
));

Certificate Helper#

The package includes a helper for working with SSL certificates:

use Cyberfusion\CoreApi\Support\CertificateHelper;

$formatted = CertificateHelper::format(file_get_contents('/path/to/certificate.crt'));
$isValid = CertificateHelper::isValid('-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----');

Laravel#

Add your credentials to the .env file:

CORE_API_USERNAME=username
CORE_API_PASSWORD=password

Create a config file core-api.php in /config:

<?php

return [
    'username' => env('CORE_API_USERNAME'),
    'password' => env('CORE_API_PASSWORD'),
];

And initialize the connector using those values:

$connector = new CoreApiConnector(
    username: config('core-api.username'),
    password: config('core-api.password'),
);

Tests#

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

composer test

For a code coverage report generated in the build/report folder:

composer test-coverage

Contribution#

Any contribution is welcome, but it should meet the PSR-12 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, please email info@vdhicts.nl instead of using the issue tracker.

License#

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