README

PHP client for the Cyberfusion Core API.

This client was built for and tested on the 1.239.0 version of the API.

Support

This client is officially supported by Cyberfusion.

Have questions? Ask your support questions on the platform. No access to the platform? Send an email to support@cyberfusion.io. GitHub issues are not actively monitored.

Author

This client was developed and is actively maintained by @dvdheiden.

The client is built upon the Saloon package. Saloon provides easy-to-use functionality (sane defaults), and full control (configurability).

Install

This client can be used in any PHP project and with any framework.

This client requires PHP 8.1 or higher. It uses Guzzle via the Saloon package. The client uses specific Laravel components, but the Laravel framework is not required.

Composer

composer require cyberfusion/core-api-client

Usage

API documentation

Refer to the API documentation for information about API requests.

Enums, Models, Requests and Resources are auto-generated based on the OpenAPI spec - so the client is completely in line with the Core API.

Getting started

Initialise the CoreApiConnector with your username and password.

The connector takes care of authentication, and offers several resources (such as VirtualHosts) and endpoints (i.e. listVirtualHosts).

use Cyberfusion\CoreApi\CoreApiConnector;

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

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

Authentication

Authenticate with the Core API using a username and password. This client takes care of authentication.

If authentication fails, AuthenticationException is thrown.

Don't have an API user? Contact Cyberfusion.

Requests

The client uses a fluent interface to build requests.

To view all possible requests:

• Start with the connector
• Go to the desired resource
• Call the desired endpoint

Code example:

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

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

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

DTOs are validated before sending the request. If invalid data is provided, ValidationException is thrown.

For example:

use Cyberfusion\CoreApi\Models\MailAliasCreateRequest;
use Respect\Validation\Exceptions\ValidationException;

$mailAlias = new MailAliasCreateRequest(
    localPart: '&^@$#^&@$#^&',
    mailDomainId: 1
);
// throw ValidationException

The exception will provide more details about the validation errors.

Responses

API responses are mapped to DTOs: all endpoints use parameters or DTOs to send data to the API.

Get model from response

To retrieve a model, call dto() on the response. This either returns:

• CoreApiModel (Collection of models)
• ValidationError model when validation failed
• DetailMessage model when something else fails

Code example:

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

Throw exception on failure

Want to throw an exception if the request fails?

Call dtoOrFail() on the response. This either returns:

• CoreApiModel (Collection of models)
• LogicException (if the response is not an HTTP 2xx)

Code example:

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

Get literal response

For advanced usage, you have full access to the literal response.

Code example:

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

if ($response->failed()) {
    echo $response->status();
}

See the Responses documentation for more information.

Filtering/sorting data

Most endpoints support filtering and sorting data.

You can use the Filter and Sort classes to build the desired filter or sort.

Specified a field that does not exist? No error will be thrown: the filter or sort is simply not applied. You are responsible for ensuring you are working with the right object.

Code example:

use Cyberfusion\CoreApi\Support\Filter;

$connector
    ->virtualHosts()
    ->listVirtualHosts(
        filter: (new Filter())->add('unix_user_id', 1),
        sort: (new Sort())->add('name', 'asc')
    );

Enums

Some properties only accept certain values (enums).

Find these values in the enum classes.

Deep dive

Middleware

There are several options to use middleware in the SDK.

Custom middleware

The most common approach: add middleware to CoreApiConnector.

use Cyberfusion\CoreApi\CoreApiConnector;
use Saloon\Http\PendingRequest;
use Saloon\Http\Response;

$connector = new CoreApiConnector(
    .. // Initialise the connector
);

$connector
    ->middleware()
    ->onRequest(function (PendingRequest $pendingRequest) {
        // Do something with the request
    });
    
$connector
    ->middleware()    
    ->onResponse(function (Response $response) {
        // Do something with the response
    });

Guzzle Middleware

You can add middleware to the Guzzle client directly. This is useful when you want to use Guzzle-specific middleware.

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

For example, when using the request-response-log package:

use Goedemiddag\RequestResponseLog\RequestResponseLogger;

$connector
    ->sender()
    ->addMiddleware(
        RequestResponseLogger::middleware(Moneybird::VENDOR)
    );

Manual requests

Don't want to use the full SDK, but easily send requests and retrieve responses from the Core API?

Use ManualRequest. Initialise the connector as usual, and send ManualRequest with the desired parameters:

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

$connector = new CoreApiConnector(
    .. // Initialise the connector
);
$response = $connector->send(new ManualRequest(
    url: '/api/v1/health',
    method: Method::GET, // optional: defaults to GET
    data: [], // optional: defaults to []
));

Integrations

Laravel

This client can be easily used in any Laravel application.

Add your API credentials to the .env file:

CORE_API_USERNAME=username
CORE_API_PASSWORD=password

Next, create a config file called core-api.php in the config directory:

<?php

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

Use those files to initialise the connector:

use Cyberfusion\CoreApi\CoreApiConnector;

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

Tests

Unit tests are available in the tests directory. Run:

composer test

To generate a code coverage report in the build/report directory, run:

composer test-coverage