README

Cyberfusion决定正式支持此包🎉 您可以在https://github.com/CyberfusionNL/cyberfusion-cluster-api-client找到官方支持的包。请确保更新命名空间，除此之外它完全相同，并且我会继续维护官方支持的包！

轻松使用托管公司Cyberfusion的集群APIAPI。此包在API的1.142版本上构建和测试。此包不是由Cyberfusion创建或维护的。

要求

此包需要PHP 7.4或更高版本，并使用Guzzle。如果可能，我打算支持PHP 7.4直到其EOL日期（2022年11月28日）。

安装

此包可以用于任何PHP项目或框架。

您可以通过composer安装此包

composer require vdhicts/cyberfusion-cluster-api-client

用法

此包只是使用Cyberfusion Cluster API的一个简单客户端。请参阅API文档以获取有关请求的更多信息。

入门

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');

沙箱模式

为了轻松测试您的实现，您可以使用沙箱模式。不会对您的集群进行更改。

要启用沙箱模式，请使用配置的第三个参数，或者单独设置它

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

或者

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

请求

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

模型

端点可能需要模型，大多数创建和更新请求都需要。

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

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

当需要提供模型时，请求执行之前将检查所需属性。如果属性缺失，将抛出RequestException。请参阅消息以获取更多详细信息。

数据过滤

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

可以为模型初始化ListFilter，这样它将自动验证提供的字段是否可用于该模型。

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

您也可以手动初始化ListFilter，但此时不会对字段进行验证。

手动发起请求

当您想直接使用API时，可以在Client上使用request()方法。此方法需要一个Request类。请参阅该类的选项。

响应

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

认证

API使用用户名和密码进行认证，并返回一个访问令牌。此包为您处理认证。要获取您的凭证，您需要联系Cyberfusion。

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

当您使用用户名和密码进行认证时，此包会自动检索访问令牌。访问令牌有效期为30分钟，所以实际上没有必要存储它。如果您仍想存储访问令牌，它将存储在Configuration类中，并可以通过$configuration->getAccessToken()访问。

手动认证

您还可以选择手动认证

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'));
}

枚举

一些模型具有应包含某些值的属性。这些值可以在枚举类中找到，仅作为参考。

异常

当发生错误时，客户端会抛出一个扩展了ClusterApiException的异常。如果您想捕获此包中的异常，那么您应该捕获这个异常。所有异常都有一个代码，这些代码可以在ClusterApiException类中找到。

部署

对集群API中的大多数对象的更改都需要部署集群。有关更多信息，请参阅集群部署。

此包会跟踪受影响的集群。客户端上的deploy方法会自动为您部署所有受影响的集群

$clusterDeployments = $client->deploy();

结果将是一个Deployment对象数组（或一个空数组，表示没有集群受到影响），这使您能够检查集群是否已正确部署

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

请参阅Deployment类以获取更多选项。

自动部署

为了方便起见，此包还能自动部署任何受影响的集群。这是一个可选行为，因为您将无法访问部署的结果。在配置中启用此行为

$configuration = new Configuration();
$configuration
    ->setAutoDeploy() // Enable the auto deployment of affected clusters
    ->setAutoDeployCallbackUrl(''); // Provide the callback url for automatic deployments

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

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

手动部署

当您禁用了自动部署并希望手动部署时，可以手动调用提交端点。您需要跟踪所有受影响的集群。

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

提交方法接受一个回调URL作为第二个参数。

Laravel

此包可以轻松地在任何Laravel应用程序中使用。我建议您将用户名和密码添加到您的.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'));

将来我可能制作一个针对Laravel的特定包，该包使用此包。

测试

单元测试位于tests文件夹中。运行方式：

composer test

当您需要生成位于build/report文件夹中的代码覆盖率报告时。运行方式：

composer test-coverage

贡献

任何贡献都受欢迎，请参阅贡献指南。

安全

如果您在此或其他Vdhicts包中发现了任何安全相关的问题，请通过电子邮件security@vdhicts.nl联系，而不是使用问题跟踪器。

支持

此包不是Cyberfusion的官方包，因此他们不提供对其的支持。如果您在此客户端中遇到问题或对此有疑问，请自由地在GitHub上打开一个问题。

许可证

此包是开源软件，许可协议为MIT许可证。

关于Vdhicts

Vdhicts是我个人的公司名称，我为该公司提供自由职业者的服务。Vdhicts为商业和教育机构开发并实施IT解决方案。