README

这是用于与 Oktave 交互的官方 PHP SDK。

安装

您可以手动安装此包或将它添加到您的 composer.json

{
  "require": {
      "confidencesapp/oktave-sdk-php": "^0.3.0"
  }
}

实例化 SDK 客户端

将配置传递给客户端

$config = [
    'client_id' => '{your_client_uuid}',
    'client_secret' => '{your_client_secret}',
    'webhook_secret' => '{your_webhook_secret}', // optional, required for request signature validation
];
$oktave = new Oktave\Client($config);

或在构造后进行配置

$oktave = new Oktave\Client()
            ->setClientID('uuid')
            ->setClientSecret('ok_cltsec_...')
            ->setWebhookSecret('ok_whsec_...'); // optional, required for request signature validation

注意：如果您不确定您的 client_id、client_secret 或 webhook_secret，请访问 您的账户 并复制它们。

对于多团队用户

将团队 ID 传递给客户端

$config = [
    // ...
    'team_id' => '{your_team_uuid}' // optional, required to specify a team ID
];
$oktave = new Oktave\Client($config);

或在构造后进行配置

$oktave = new Oktave\Client($config)
            ->setTeamId('uuid'); // optional, required to specify a team ID

注意：如果没有指定 team，则默认使用 OAuth 客户端声明的团队。

注意：如果您不确定您的 team 是什么，请访问 您的账户 并复制它。

不带 ID 重置为默认团队

// set the team to null.
$oktave = new Oktave\Client($config)
            ->setTeamId(null);

注意：团队值可以随时更新，例如在资源调用之间。

本地客户

如果您是本地客户并且拥有自己的具有自定义域名的基础设施，您可以配置客户端使用您的域

$oktave->setBaseURL('https://api.yourdomain.com');

或将 api_endpoint 字段添加到您传递给构造函数的 $config 数组中。

使用客户端

多个资源

返回您的资源列表

// return a list of your blacklist items 
$oktave->blacklistItems->all();

分页

返回分页的您的资源列表

// return a list of your paginated blacklist items
// items per page accepted values : 10, 20, 50, 100

$result = $oktave->blacklistItems->perPage(20)->page(5)->all();
$result->data() // contains the ressource collection
$result->meta() // contains the current pagination meta

/* [ 'current_page' => 5, 'per_page' => 20, 'total' => 95 ] */

通过 ID 单个资源

通过 ID 获取资源

$oktave->blacklistItems->get($blacklistItemID);

处理异常

除了可能因调用而发生的错误之外，还可能抛出其他异常。要处理它们，只需在您的调用中包含 try catch 块

try {
    $oktave->blacklistItems->all();
} catch (Exception $e) {
    // do something with $e
}

内部，可能会抛出几个自定义异常 - 更多信息请参阅 Exceptions 目录。

Webhook 请求验证

验证 webhook 请求签名

// return true if the request signature is valid 
$oktave->webhooks->verifySignatureFromGlobals();

$eventID = isset($_SERVER['HTTP_OKTAVE_EVENT_ID']) ? $_SERVER['HTTP_OKTAVE_EVENT_ID'] : null;
$requestTimestamp = isset($_SERVER['HTTP_OKTAVE_TIMESTAMP']) ? (int) $_SERVER['HTTP_OKTAVE_TIMESTAMP'] : null;
$signature = isset($_SERVER['HTTP_OKTAVE_SIGNATURE']) ? $_SERVER['HTTP_OKTAVE_SIGNATURE'] : null;

// return true if the request signature is valid 
$oktave->webhooks->verifySignature($eventID, $requestTimestamp, $signature);

测试

phpunit

生成覆盖率报告

phpunit --coverage-html ./ignore