README

此SDK可用于简化PHP与Upmind API的集成。

需求
安装
用法
- 入门
- 异常
- 分页
- 关系
- 创建资源
- 手动使用
变更日志
贡献
鸣谢
许可协议
Upmind

需求

PHP 7.4, 8.0, 8.1, 8.2或8.3
Composer
HTTPlug兼容客户端例如，Guzzle
Upmind Starter计划或更高

安装

composer require upmind/sdk

此库使用HTTPLUG抽象进行HTTP请求，使用发现来自动检测要使用的HTTP客户端。由于库依赖于虚拟包psr/http-client-implementation，因此您需要首先安装兼容的HTTP客户端实现，例如php-http/guzzle7-adapter。

可以使用以下PSR的任何实现

用法

入门

要使用SDK，您首先需要在Upmind管理区域设置中创建一个API令牌。您还应记录您的品牌ID。

首先，您需要使用您的API令牌和品牌ID创建一个Config实例。然后，使用它来创建一个Api客户端实例。将debug选项设置为true以将API请求和响应流式传输到STDERR；或者，您可以在实例化API时传递一个替代的PSR-3兼容的记录器。

然后您可以得到一个服务实例以开始进行API请求。

use Upmind\Sdk\Api;
use Upmind\Sdk\Config;

$config = new Config(
    token: 'your-api-token',
    brandId: 'your-brand-id',
    withoutNotifications: true, // don't trigger notifications for create/update/delete requests
    debug: true, // stream api requests + responses to STDERR by default
);
$api = new Api($config);
$service = $api->clientService();

$clientId = '467029e9-d574-1484-680f-e10683283ed5';

$response = $service->getClient($clientId);
$clientData = $response->getResponseData();
// ...

异常

此库抛出的所有异常都实现了标记接口Upmind\Sdk\Exceptions\UpmindSdkException。

默认情况下，API错误（非2xx）响应将抛出Upmind\Sdk\Exceptions\HttpException实例，其中包含API错误响应数据。您可以通过使用带有restfulExceptions: false的Config实例来关闭HttpException。

启用HTTP异常

启用HTTP异常（默认），无需检查HTTP代码或响应体来检测错误，因为SDK将为任何非2xx HTTP响应抛出异常。

use Upmind\Sdk\Api;
use Upmind\Sdk\Config;
use Upmind\Sdk\Exceptions\HttpException;
use Upmind\Sdk\Exceptions\ValidationException;

$config = new Config(
    token: 'your-api-token',
);
$api = new Api($config);
$service = $api->clientService();

try {
    $clientId = '467029e9-d574-1484-680f-e10683283ed5';

    $clientData = $service->getClient($clientId)->getResponseData();
} catch (ValidationException $e) {
    // HTTP 422 error containing an array of validation errors
    $error = $e->getApiError();
    $validationErrors = $e->getValidationErrors();
    // ...
} catch (HttpException $e) {
    // Any other HTTP error response
    $error = $e->getApiError();
    // ...
}

禁用HTTP异常

禁用HTTP异常时，您可以通过检查ApiResponse来确定是否成功。

use Upmind\Sdk\Api;
use Upmind\Sdk\Config;

$config = new Config(
    token: 'your-api-token',
    restfulExceptions: false, // don't throw exceptions for API error responses
);
$api = new Api($config);
$service = $api->clientService();

$clientId = '467029e9-d574-1484-680f-e10683283ed5';

$response = $service->getClient($clientId);
if ($response->isSuccessful()) {
    $clientData = $response->getResponseData();
    // ...
} else {
    $error = $response->getResponseError();
    // ...
}

分页

大多数列表请求将返回分页结果。SDK允许您传递一个QueryParams对象来通过设置limit（默认10）和offset（默认0）查询参数来控制分页。

use Upmind\Sdk\Data\QueryParams;

$queryParams = QueryParams::new()
    ->setLimit(20) // returns up to 20 results
    ->setOffset(100); // skips the first 100 results

$clients = $api->clientService()
    ->listClients($queryParams)
    ->getResponseData();
foreach ($clients as $clientData) {
    $clientId = $clientData['id'];
    // ...
}

关系

某些资源与其他资源有关联。您可以通过在GET请求中设置with查询参数来指定要加载的关系。这减少了获取相关资源所需的API请求数量。

use Upmind\Sdk\Data\QueryParams;

$clientId = '467029e9-d574-1484-680f-e10683283ed5';
$queryParams = QueryParams::new()
    ->setWith(['emails', 'addresses']); // load the client's emails and addresses

$clientData = $api->clientService()
    ->getClient($clientId, $queryParams)
    ->getResponseData();
foreach ($clientData['emails'] as $emailData) {
    // ...
}
foreach ($clientData['addresses'] as $addressData) {
    // ...
}

创建资源

创建方法使用包含setter方法的DTO进行类型化，以帮助您识别哪些参数可用。资源成功创建后，将返回一个id，可用于稍后检索和管理该资源。

use Upmind\Sdk\Data\Services\CreateEmailParams;

$clientId = '467029e9-d574-1484-680f-e10683283ed5';
$createEmail = CreateEmailParams::new()
    ->setEmail('harry@upmind.com')
    ->setDefault(true);

$emailData = $api->emailService()
    ->createEmail($clientId, $createEmail)
    ->getResponseData();
$emailId = $emailData['id'];
// ...

手动使用

某些资源可能没有SDK中的对应服务。您可以使用Api客户端手动向任何端点发出请求。以下是一个示例，展示如何将现有订单（合同产品）导入Upmind。

use Upmind\Sdk\Data\BodyParams;

$clientId = '467029e9-d574-1484-680f-e10683283ed5';
$hostingServerId = 'e5750263-4647-9ed1-26a2-1053288d79e9'; // server provision configuration id
$hostingProductId = 'd6d97847-5d49-2153-2def-d163e080e253'; // catalogue product id
$premiumSupportProductId = 'd9860720-492e-710d-0d6b-8165d83d345e'; // catalogue product option id
$hostingLocationProductId = '84856376-2e90-516e-607a-e17d48302de9'; // catalogue product attribute id

$body = BodyParams::new()
    ->setParam('category_slug', 'new_contract')
    ->setParam('client_id', $clientId)
    ->setParam('currency_code', 'GBP')
    ->setParam('manual_import', true) // setting to true allows us to override activation/due dates
    ->setParam('activation_date', '2022-05-01') // initial order activation date
    ->setParam('next_due_date', '2024-10-01') // current date the order is paid up until
    ->setParam('products', [
        [
            'product_id' => $hostingProductId,
            'quantity' => 1,
            'billing_cycle_months' => 6, // renews every 6 months
            'selling_price' => 35.99, // the net price of the base product
            'provision_configuration_id' => $hostingServerId,
            'provision_field_values' => [ // hosting product provision fields
                'domain' => 'example.com',
                'username' => 'example2',
            ],
            'options' => [
                [
                    'product_id' => $premiumSupportProductId,
                    'quantity' => 1,
                    'billing_cycle_months' => 6, // renews with the base product
                    'selling_price' => 30.00, // the net price of the option; this gets added to the base product price
                ]
            ],
            'attributes' => [
                [
                    'product_id' => $hostingLocationProductId,
                ]
            ]
        ]
    ]);

$responseData = $api->post('/api/admin/orders/quick', $body)->getResponseData();
$orderNumber = $responseData['number'];
$contractId = $responseData['contract_id'];
$contractProductId = $responseData['products'][0]['contracts_product_id'];
// ...

变更日志

有关最近更改的更多信息，请参阅变更日志。

贡献

请参阅CONTRIBUTING获取详细信息。

鸣谢

许可协议

GNU通用公共许可证版本3（GPLv3）。请参阅许可文件以获取更多信息。

Upmind

使用Upmind.com销售、管理和支持网页托管、域名、SSL证书、网站构建器等。

upmind / sdk

维护者

详细信息