README

此库的核心目的是管理Helpscout API。我为了备份我们公司的文档，单独构建了这个工具。

注意!!

我正在逐渐添加更多端点，以使这个工具更有用。

安装

composer install adambalan/helpscout-api

API

所有核心API端点类都位于/Api/Get/下。

它们都接受一个GuzzleHttp客户端和一个ApiKey Contract。

契约

这些契约是接口，是基本值对象 - 根据当前API需求，基于get/set方法，以下契约存在：

• ApiKey
• Article
• Category
• Collection
• Redirect
• site
• ArticlePostBody
• CategoryPostBody
• CollectionPostBody
• RequestPool

这些接口被实现，并在需要的地方传递给端点类方法。

有关更多信息，请参阅生成的文档。

示例

要理解的核心是结构和流程如下：

• 获取所有集合
• 获取所有分类（基于集合ID）
• 获取所有文章（基于分类ID）
  • 根据上述返回的文章ID获取单个文章。

您也可以通过集合获取文章

• 获取所有集合
• 根据集合ID获取所有文章
  • 根据上述文章ID获取单个文章。

文章将返回文章列表，不幸的是，您必须使用文章ID来获取特定信息，例如单个文章的文本。

获取所有文章

要获取所有文章，您必须有一个分类ID，您可以从获取所有分类中获得该ID，这反过来又需要一个集合ID。

use HelpscoutApi\Api\Get\Articles;
use HelpscoutApi\Contracts\ApiKey; // We will pretend we implemented this as ApiKeyValue;
use HelpscoutApi\Contracts\Category; // We will pretend we implemented this as CategoryValue;
use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'https://docsapi.helpscout.net/v1/',
]);

$apiKey = new ApiKeyValue('xxxxxxxxxx');

$categoryValue = new CategoryValue('12345667');

$articles = new Article($client, $apiKey);
$articleJSON = $articles->getAll($categoryValue);

// Do something with $articleJSON.

带有参数获取所有文章

use HelpscoutApi\Api\Get\Articles;
use HelpscoutApi\Contracts\ApiKey; // We will pretend we implemented this as ApiKeyValue;
use HelpscoutApi\Contracts\Category; // We will pretend we implemented this as CategoryValue;
use HelpscoutApi\Params\Article as ArticleParams;
use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'https://docsapi.helpscout.net/v1/',
]);

$apiKey = new ApiKeyValue('xxxxxxxxxx');

$categoryValue = new CategoryValue('12345667');

// You can set the url params that come back as `?sort=number&status=number`:

$articleParams = new ArticleParams();
$articleParams->sort('number');
$articleParams->status('name');

$articles = new Article($client, $apiKey);

// We then pass $articleParams
$articleJSON = $articles->getAll($categoryValue, $articleParams);

// Do something with $articleJSON.

发布文章

相同的概念也适用于发布分类或集合，只需将ArticlePostBody替换为分类或集合的post body契约。

use HelpscoutApi\Api\Post\Article;
use HelpscoutApi\Contracts\ApiKey; // We will pretend we implemented this as ApiKeyValue;
use HelpscoutApi\Contracts\ArticlePostBody; // We will pretend we implemented this as ArticlePostBody;
use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'https://docsapi.helpscout.net/v1/',
]);

$apiKey = new ApiKeyValue('xxxxxxxxxx');

$articlePostBody->collectionID('123');
$articlePostBody->name('article name');
$articlePostBody->text('something');

$article = new Article($client, $apiKey);
$article->create($articlePostBodyValue);

// This will return a response, see https://developer.helpscout.com/docs-api/articles/create/
// for more information.

删除文章

这些概念也适用于分类和集合。

use HelpscoutApi\Api\Delete\Article;
use HelpscoutApi\Contracts\ApiKey;
use HelpscoutApi\Contracts\Article as ArticleContract;
use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'https://docsapi.helpscout.net/v1/',
]);

$apiKey = new ApiKeyValue('xxxxxxxxxx');

$articleContract = new ArticleContract('1234');
$article         = new Article($client, $apiKey);

$article->delete($articleContract); // Returns the \GuzzleHttp\Psr7\Response

您可以通过测试来更好地了解如何使用端点。

更新文章

注意!!

目前只能更新文章。

更新文章的方式与创建文章相同，只有一个小的不同，我们传递一个ArticlePutBody契约。

此契约包含三个方法：id(string $articleId)，getId(): string，articlePostBody(ArticlePostBody $articlePostBody)

还有一个方法，即createPutBody()，它用于创建请求的实际JSON。

与创建类似，您可以使用单个、异步和返回更新请求来更新单个文章，所有这些都使用PUT请求。

use HelpscoutApi\Api\Post\Article;
use HelpscoutApi\Contracts\ApiKey; // We will pretend we implemented this as ApiKeyValue;
use HelpscoutApi\Contracts\ArticlePostBody; // We will pretend we implemented this as ArticlePostBody;
use HelpscoutApi\Contracts\ArticlePutBody; // We will pretend we implemented this as ArticlePutBody;
use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'https://docsapi.helpscout.net/v1/',
]);

$apiKey = new ApiKeyValue('xxxxxxxxxx');

$articlePostBody->collectionID('123');
$articlePostBody->name('article name');
$articlePostBody->text('something');

$articlePutBody->id('articleId');
$articlePutBody->articlePostBody($articlePostBody);

$article = new Article($client, $apiKey);
$article->update($articlePutBody);

// This will return a response, see https://developer.helpscout.com/docs-api/articles/update/
// for more information.

异步请求和池

注意!!

目前这仅适用于文章和分类

当您想以异步方式执行操作或您需要向特定端点发布未定义数量的实体时，可以使用 createAsync 和 createRequest。其中一个将返回一个 Promise，另一个旨在与 Guzzle Pools 一起使用；

让我们看看如何实现它。

createAsync()

use Psr\Http\Message\ResponseInterface;
use GuzzleHttp\Exception\RequestException;

// ... Set up your article info to be posted, see previous examples.

$promise = $article->createAsync($articlePostBodyValue);
$promise->then(function(ResponseInterface $ri) {
  echo $ri->getStatusCode();
},
function(RequestException $e) {
  echo $e->getMessage();
});

如我们所见，createAsync() 仅返回一个Promise。

createRequest()

创建请求旨在与RequestPool契约一起使用来设置请求，因为这个方法仅返回一个请求对象。然后您将请求设置到池数组中，并将RequestPool实例传递到Pool类方法pool中，以及客户端实例到实例化中。

从那里，您可以使用拒绝的回调函数和可选的成功回调函数调用pool。

use HelpscoutApi\Contracts\RequestPool;
use HelpscoutApi\Api\Pool;

// ... Set up your article info to be posted, see previous examples.

$request = $article->createRequest($articlePostBodyValue);

$requestPool->pushRequest($request); // Push the request
$request->setConcurrency(1); // How many should we do before we wait for them all to complete?

$pool = new Pool($client);
$pool->pool($requestPool, function($reason, $index){ ... }, function($response){ ... });

// The first call back function is called when we are rejected.
// The second is optional and only called on success.

注意!!

如果并发数未设置或小于等于0，我们将默认设置为20。

处理响应

Helpscout不会返回包含创建对象的JSON的响应体，相反，您可能希望的大量信息都在头部，至少在创建新资源时，重要的是资源的地理位置和ID。

use HelpscoutApi\Request\Request;

// See above for creating an article:

$response = $article->create($articlePostBodyValue);
$responseObject = new Request($response);

$responseObject->getLocation();  // Returns the location of the created object.
$responseObject->getContents();  // Returns the contents of the returned body.

请参阅Response类的文档