README

Cyberfusion Core API 客户端。

此客户端是为 API 的 1.230.1 版本构建和测试的。

支持

此客户端由 Cyberfusion 正式支持。如果您有任何问题，请在 GitHub 上提交问题或通过电子邮件support@cyberfusion.nl联系。

创建者：@dvdheiden。

要求

此客户端需要 PHP 8.1 或更高版本，并使用 Guzzle。

安装

此客户端可以用于任何 PHP 项目和任何框架。

使用 Composer 安装客户端

composer require cyberfusion/cluster-api-client

用法

有关 API 请求的信息，请参阅API 文档。

入门

use Cyberfusion\ClusterApi\Client;
use Cyberfusion\ClusterApi\Configuration;
use 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');

请求

端点方法可能需要过滤器、模型和 ID。方法类型提示告诉您哪些输入被请求。

模型

端点可能请求一个模型。大多数创建和更新请求都是这样。

$unixUserUsername = 'foo';

$unixUser = (new UnixUser())
    ->setUsername($unixUserUsername)
    ->setPassword('bar')
    ->setDefaultPhpVersion('7.4')
    ->setVirtualHostsDirectory(sprintf('/home/%d', $unixUserUsername))
    ->setClusterId(1);

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

在执行请求之前，需要提供模型时，会检查所需的属性。

如果属性缺失，将抛出 RequestException。有关更多详细信息，请参阅错误消息。

过滤数据

某些端点需要 ListFilter 并根据过滤器返回模型列表。还可以更改排序顺序。

模型过滤器

可以为模型初始化 ListFilter，以便自动验证提供的字段是否适用于模型。

use Cyberfusion\ClusterApi\Enums\Sort;
use Cyberfusion\ClusterApi\Models\VirtualHost;
use Cyberfusion\ClusterApi\Support\FilterEntry;
use Cyberfusion\ClusterApi\Support\SortEntry;

$listFilter = VirtualHost::listFilter()
    ->filter(new FilterEntry('server_software_name', 'Apache'))
    ->filter(new FilterEntry('domain', 'cyberfusion.nl'))
    ->sort(new SortEntry('domain', Sort::DESC));

手动创建过滤器

您可以手动初始化 ListFilter，但如果字段适用于模型则不会进行验证。

$listFilter = (new ListFilter())
    ->filter(new FilterEntry('server_software_name', 'Apache'))
    ->filter(new FilterEntry('domain', 'cyberfusion.nl'))
    ->sort(new SortEntry('domain', Sort::DESC));

或直接提供条目和排序

$listFilter = (new ListFilter())
    ->setFilters([
        new FilterEntry('server_software_name', 'Apache'),
        new FilterEntry('domain', 'cyberfusion.nl'),
    ])
    ->setSort([
        new SortEntry('domain', Sort::DESC)
    ]);
);

替代方法

此包曾提供此方法构建过滤器。由于向后兼容性，此功能仍然可用。

$listFilter = ListFilter::forModel(new Cluster())
    ->filter('server_software_name', 'Apache')
    ->filter('domain', 'cyberfusion.nl')
    ->sort('domain', Sort::DESC);

或直接提供条目和排序

$listFilter = (new ListFilter())
    ->setFilters([
        ['field' => 'server_software_name', 'value' => 'Apache'],
        ['field' => 'domain', 'value' => 'cyberfusion.nl'],
    ])
    ->setSort([
        ['field' => 'domain', 'value' => Sort::DESC],
    ]);
);

手动发送请求

要直接使用 API，请使用 Client 上的 request() 方法。此方法需要一个 Request 类。请参阅类本身以了解其选项。

响应

端点方法在请求因超时而失败时抛出异常。当 API 以 HTTP 协议错误回复时，仍然返回 Response 类。检查请求是否成功：使用 $response->isSuccess()。API 响应会自动转换为模型。

身份验证

API 使用用户名和密码进行身份验证并返回访问令牌。此客户端负责身份验证。要获取凭据，请联系 Cyberfusion。

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

当您使用用户名和密码进行身份验证时，此客户端会自动检索访问令牌。

访问令牌有效期为 30 分钟，因此无需存储。如果要存储，请使用 $configuration->getAccessToken() 访问。

手动身份验证

use Cyberfusion\ClusterApi\Client;
use Cyberfusion\ClusterApi\ClusterApi;
use Cyberfusion\ClusterApi\Configuration;
use 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'));
}

枚举

某些属性应包含某些值。这些值可以在枚举类中找到。

异常

在发生错误的情况下，客户端会抛出一个扩展 ClusterApiException 的异常。

所有异常都有一个代码。这些可以在 ClusterApiException 类中找到。

Laravel

此客户端可以轻松用于任何 Laravel 应用程序。将您的 API 凭据添加到 .env 文件。

CLUSTER_USERNAME=username
CLUSTER_PASSWORD=password

接下来，在 config 目录下创建一个名为 cluster.php 的配置文件

<?php

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

使用这些文件构建配置

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

测试

单元测试在 tests 目录中可用。运行

composer test

要在 build/report 目录中生成代码覆盖率报告，请运行

composer test-coverage

贡献

欢迎贡献力量。请参阅贡献指南。

安全性

如果您发现任何安全相关的问题，请通过电子邮件 support@cyberfusion.nl 反馈，而不是使用问题跟踪器。

许可证

此客户端是开源软件，采用MIT许可证。