PHP client for the Cyberfusion Core API.
This client was built for and tested on the 1.239.0 version of the API.
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.
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).
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 require cyberfusion/core-api-client
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.
Initialise the CoreApiConnector with your username and password.
The connector takes care of authentication, and offers several resources (e.g. VirtualHosts) and endpoints (e.g. listVirtualHosts).
use Cyberfusion\CoreApi\CoreApiConnector;
$connector = new CoreApiConnector(
username: 'username',
password: 'password'
);
$virtualHosts = $connector
->virtualHosts()
->listVirtualHosts()
->dto();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.
The client uses a fluent interface to build 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.
Code example:
use Cyberfusion\CoreApi\Models\MailAliasCreateRequest;
use Respect\Validation\Exceptions\ValidationException;
$mailAlias = new MailAliasCreateRequest(
localPart: '&^@$#^&@$#^&',
mailDomainId: 1
);
// throw ValidationExceptionThe exception contains ValidationError objects in the errors collection.
Coe example:
try {
$virtualHost = $connector
->virtualHosts()
->createVirtualHost(...)
->dto();
} catch (RequestFailedException $exception) {
echo $exception->getDetailMessage()->getDetail();
} catch (ValidationException $exception) {
foreach ($exception->errors() as $error) {
echo $error->getMsg();
}
}API responses are mapped to DTOs: all endpoints use parameters or DTOs to send data to the API.
To retrieve a model, call dto() on the response. This either returns:
CollectionofCoreApiModelinstancesCoreApiModel
Code example:
$virtualHosts = $connector
->virtualHosts()
->listVirtualHosts()
->dto();If a request returns an unexpected HTTP status code, RequestFailedException is thrown.
The exception includes the response, and - if returned - a DetailMessage object with more information.
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.
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')
);Some properties only accept certain values (enums).
Find these values in the enum classes.
There are several options to use middleware in the SDK.
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
});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
);Code example, when using the request-response-log package:
use Goedemiddag\RequestResponseLog\RequestResponseLogger;
$connector
->sender()
->addMiddleware(
RequestResponseLogger::middleware(Moneybird::VENDOR)
);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 []
));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'),
);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