README

使用 Guzzle 的简单 API 包装器来调用 Freshsales。它支持 Freshsales 提供的 REST API，并具有基本的速率限制功能。还支持：通过 Guzzle 的承诺进行异步请求。

此库需要 PHP >= 7。

PS：此项目大部分灵感来自（即复制 <3 ）osiset/Basic-Shopify-API。

安装

推荐的安装方式是通过 composer。

composer require ianfortier/basic-freshsales-api

使用

将 use ianfortier\BasicFreshsalesAPI; 添加到您的导入中。

REST（同步）

对于 REST 调用，需要商店域名和访问令牌。

$api = new BasicFreshsaleAPI();

// Now run your requests...
$resul = $api->rest(...);

REST（异步）

对于 REST 调用，需要商店域名和访问令牌。

$api = new BasicFreshsaleAPI();

// Now run your requests...
$promise = $api->restAsync(...);
$promise->then(function ($result) {
  // ...
});

发送请求

REST

请求使用 Guzzle 发送。

$api->rest(string $type, string $path, array $params = null, array $headers = [], bool $sync = true);

type 指的是 GET、POST、PUT、DELETE 等
path 指的是 API 路径，例如：/api/leads
params 指的是要传递到路径的参数数组，例如：['email' => 'customer@email.com']
headers 指的是要随请求可选发送的自定义头数组，例如：['X-Freshsales-Test' => '123']
sync 指的是请求是否为同步或异步。

您可以使用别名 restAsync 来跳过将 sync 设置为 false。

如果同步为 true（常规 REST 调用）

请求的返回值将包含一个对象，其中包含

response 完整的 Guzzle 响应对象
body JSON 解码的响应体（数组）
bodyObject JSON 解码的响应体（stdClass）

注意：request() 也将别名到 rest()。

如果同步为 false（restAsync 调用）

请求的返回值将是一个 Guzzle 承诺，您可以根据自己的需要处理。

承诺的返回值将包含一个对象，其中包含

response 完整的 Guzzle 响应对象
body JSON 解码的响应体（数组）
bodyObject JSON 解码的响应体（stdClass）

$promise = $api->restAsync(...);
$promise->then(function ($result) {
  // `response` and `body` available in `$result`.
});

传递额外的请求选项

如果您想向创建的 Guzzle 客户端传递额外的请求选项，请将它们作为构造函数的第二个参数传递。

$api = BasicFreshsaleAPI(true, ['connect_timeout' => 3.0]);

在上面的例子中，第二个参数中的数组将被合并到创建的 Guzzle 客户端中。

检查 API 限制

每次请求后，API 调用限制都会更新。要访问它们，请简单使用

// Returns an array of left, made, and limit.
// Example: ['left' => 79, 'made' => 1, 'limit' => 80]
$limits = $api->getApiCalls('rest');

速率限制

此库包含一个内置的基本速率限制器，默认禁用。它将在 x 微秒内休眠，以确保您不会超过 Freshsales 的调用限制。

默认情况下，周期设置为 500ms，并添加了一个 100ms 的安全缓冲。

启用速率限制

正常设置您的 API 实例，并添加一个

$api->enableRateLimiting();

这将使用默认的500ms循环和100ms缓冲区启用速率限制。要更改此设置，请执行以下操作

$api->enableRateLimiting(0.25 * 1000, 0);

这将设置循环为250ms和0ms缓冲区。

禁用速率限制

如果您之前已启用它，只需运行

$api->disableRateLimiting();

检查速率限制状态

$api->isRateLimitingEnabled();

错误

此库通过Guzzle内部仅捕获400-500状态范围的错误。您能够检查此类错误并获取其响应状态码和主体。

$call = $api->rest('GET', '/xxxx/non-existant-route-or-object');

if ($call->errors) {
  echo "Oops! {$call->status} error";
  var_dump($call->body);

  // Original exception can be accessed via `$call->exception`
  // Example, if response body was `{"error": "Not found"}`...
  /// then: `$call->body` would return "Not Found"
}

日志记录

此库接受PSR兼容的记录器。

$api->setLogger(... your logger instance ...);

LICENSE

本项目遵循MIT许可证发布。

ianfortier / basic-freshsales-api

维护者

详情