README

客户端用于向 Shiptheory V1 REST API 发送 HTTP 请求。处理日志记录、认证/刷新令牌。尽可能使用 PSR 兼容接口和依赖注入。

在 Pakagist 上查看： https://packagist.org.cn/packages/dan-rogers/shiptheory-php-client

查看 Shiptheory API 文档： https://shiptheory.com/developer/index.html

安装

composer require dan-rogers/shiptheory-php-client

用法

客户端结合现有的 PSR 标准使用 DI，以便您可以在您喜欢的环境中使用您喜欢的库进行操作。在实例化时所需的 HTTP 客户端必须实现 PSR18，而您在实例化时可以使用的可选记录器必须实现 PSR3。

令牌

令牌类型

Shiptheory 提供 2 种认证方式

1. 基于凭据的访问：用户必须将他们的登录凭据传递给 /token 端点以交换 JWT 访问令牌，然后可以在后续请求中使用此令牌。此令牌有效期为 1 小时，但可以随时生成新的令牌。
2. 永久令牌：您可以通过登录您的帐户并转到 https://helm.kubernetes.ac.cniptheory.com/user_tokens 来生成一个不变的、永久的令牌。

实现

要使用凭据访问令牌，您应将 ShiptheoryClient\Authorization\CredentialsAccessToken 的实例传递给新的 Shiptheory 客户端实例。令牌将自动刷新。在实例化时，您必须将用户名和密码作为参数传递。

<?php declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use ShiptheoryClient\Authorization\CredentialsAccessToken;

$token = new CredentialsAccessToken('dan.rogers@shiptheory.com', 'password');

要使用永久访问令牌，您应将 ShiptheoryClient\Authorization\PermanentAccessToken 的实例传递给新的 Shiptheory 客户端实例。在实例化时，您必须将永久令牌作为参数传递。

<?php declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use ShiptheoryClient\Authorization\PermanentAccessToken;

$token = new PermanentAccessToken('ABC12345678');

示例用法

以下示例使用 guzzlehttp/guzzle 作为客户端，CredentialsAccessToken 作为授权，以及 monolog/monolog 作为日志记录。

<?php declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use GuzzleHttp\Client;
use Monolog\Level;
use Monolog\Logger;
use Monolog\Handler\StreamHandler;
use ShiptheoryClient\Authorization\CredentialsAccessToken;
use ShiptheoryClient\ShiptheoryClient;

$client = new Client();
$token =  new CredentialsAccessToken('dan.rogers@shiptheory.com', 'password');

$log = new Logger('Shiptheory');
$handler = new StreamHandler('/path/to/your/logfile.log', Level::Debug);
$handler->setFormatter(new LineFormatter(null, null, true, true));
$log->pushHandler($handler);

$shiptheory = new ShiptheoryClient($client, $token, $log, 'partner_tag');

$res = $shiptheory->listTags();
var_dump($res->getBody()->getContents());

日志记录

启用日志记录

日志记录通过 DI 提供。在实例化 ShiptheoryClient 时传递任何 PSR3 兼容的记录器对象，请求和响应的日志记录将自动处理。如果没有提供记录器，则所有日志将通过使用 Psr\Log\NullLogger 被丢弃。

示例日志输出

使用日志记录时，您的 PSR7 消息将被转换为等效的 HTTP 请求。以下是在 monolog/monlog 中生成的，但无论您使用哪种 PSR3 兼容的日志记录解决方案，事务 ID 后跟请求或响应的字符串表示都将保持一致。

[2024-03-24T10:03:48.821264+00:00] Shiptheory.DEBUG: e1232cc3b4683effe04f3e4605a040ea
GET /v1/tags HTTP/1.1
Host: api.shiptheory.com
Accept: application/json
Content-Type: application/json
Authorization: REDACTED
[2024-03-24T10:03:49.399426+00:00] Shiptheory.DEBUG: e1232cc3b4683effe04f3e4605a040ea
HTTP/1.1 200 OK
Server: nginx/1.14.1
Date: Sun, 24 Mar 2024 10:03:18 GMT
Content-Type: application/json; charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive
Set-Cookie: AWSALB=h7p5oZdry0zB/l9D2nJyyV627QsNZ8pfT+XBRrjbnlwF4I118DxKxM5o8PvYTcdPT7pJYKlFf0G6A7szXto1OgnJNnBBCFGJxzU0yFfr3cLL/+n0J2L45yCrgVla; Expires=Sun, 31 Mar 2024 10:03:18 GMT; Path=/, AWSALBCORS=h7p5oZdry0zB/l9D2nJyyV627QsNZ8pfT+XBRrjbnlwF4I118DxKxM5o8PvYTcdPT7pJYKlFf0G6A7szXto1OgnJNnBBCFGJxzU0yFfr3cLL/+n0J2L45yCrgVla; Expires=Sun, 31 Mar 2024 10:03:18 GMT; Path=/; SameSite=None; Secure
X-XSS-Protection: 1; mode=block

{"tags":[{"id":4,"name":"My Tag","background_colour":"#008000","text_colour":"#FFF"},{"id":7,"name":"Another Tag","background_colour":"#800080","text_colour":"#FFF"},{"id":326,"name":"A third tag","background_colour":"#FF0000","text_colour":"#FFF"},{"id":329,"name":"Wow a fourth one","background_colour":"#FF8C00","text_colour":"#FFF"}],"pagination":{"page":1,"pages":1,"results":4,"results_per_page":25,"limit":false}}

使用 Shiptheory 合作伙伴标签

"如果您正在开发一个将供多个公司使用或您打算以任何方式分发的应用程序，您必须在所有请求中包含 Shiptheory-Partner-Tag http 请求头。请联系 Shiptheory 支持以获取合作伙伴标签。此服务免费，标签用于为顾客和合作伙伴提供更好的支持。"- API 文档"

为了将合作伙伴标签添加到您的 API 请求中，在实例化新的 ShiptheoryClient 时将其作为第四个参数添加。

$client = new ShiptheoryClient($client, $token, $log, 'partner_tag');