README

由Footbridge Media开发者Garet C. Green创建的未经官方认证的PHP 8.1+ Accelo PHP SDK。

要求

• Guzzle 7.4及以上
• PHP 8.1及以上

用法

首先，您必须在请求成功处理之前设置身份验证和凭据。

使用composer安装

composer require footbridge-media/accelo-php-sdk

通过oAuth为Web应用程序使用验证您的Accelo帐户

此库包含一个用于CLI使用的内置验证器，允许您使用他们拥有的oAuth2 API验证您的Accelo员工帐户。

请确保您有部署名称、客户端ID和客户端密钥，然后通过CLI运行以下脚本。

php vendor/footbridge-media/accelo-php-sdk/src/Resources/CLIScripts/WebAuthenticate.php

按照提示提供他们请求的信息，直到输出一个URL。

Enter your Accelo deployment name and press enter:
Enter your Accelo web client ID and press enter:
Enter your Accelo web client secret key and press enter:
Visit this URL in your browser to authorize this library to use your Accelo account for the API - URL_WILL_BE_HERE

复制完整的URL并在网页浏览器中访问。

通过链接登录您的Accelo帐户，它将提供一个数字访问代码。返回CLI提示，它要求您提供此访问代码。

After allowing access, enter the access code you were given here and press enter: 

您将获得使用此库和Accelo API所需的所有必要的access_token和refresh_token。

oAuth authorization succeeding. Your access codes and expiratory information is below. Please keep it safe in the dark:
Array                                                                                 
(                                                                                     
    [access_token] => TOKEN_HERE
    [refresh_token] => TOKEN_HERE
    [expires_in] => SECONDS_UNTIL_EXPIRES
    [expires_on] => DATE_OF_EXPIRATORY
    [deployment_uri] => DEPLOYMENT_URL
    [token_type] => TOKEN_TYPE
)

将这两个令牌（访问和刷新）保存下来以供在此库中使用。通常，您会将它们存储在非提交环境文件中。

您还可以选择存储expires_in和expires_on信息，以便您知道何时需要更新您的令牌。您现在可以继续使用此库的其余部分。

验证服务应用程序

如果您想使用服务应用程序而不是验证Web用户，则过程类似于上面的验证部分。

请确保您有部署名称、客户端ID和客户端密钥，然后通过CLI运行以下脚本。从应用程序的根目录运行此脚本。

php vendor/footbridge-media/accelo-php-sdk/src/Resources/CLIScripts/ServiceAuthenticate.php

按照提示提供他们请求的信息。

Enter your Accelo deployment name and press enter:
Enter your Accelo web client ID and press enter:
Enter your Accelo web client secret key and press enter:

如果所有信息都正确，则Accelo的oAuth API将授权您的应用程序3年。然后您将获得使用此库和Accelo API所需的所有必要的access_token。

oAuth authorization succeeding. Your access codes and expiratory information is below. Please keep it safe in the dark:
Array                                                                                 
(                                                                                     
    [access_token] => TOKEN_HERE
    [refresh_token] => 
    [expires_in] => SECONDS_UNTIL_EXPIRES
    [expires_on] => DATE_OF_EXPIRATORY
    [deployment_uri] => DEPLOYMENT_URL
    [token_type] => TOKEN_TYPE
)

您只需要为服务应用程序使用access_token。

您还可以选择存储expires_in和expires_on信息，以便您知道何时需要更新您的令牌。您现在可以继续使用此库的其余部分。

启动新的Accelo对象

use FootbridgeMedia\Accelo\Accelo;

$accelo = new Accelo();

此对象将被赋予一个身份验证对象和一个凭证对象。然后它将用于调用API。

客户端身份验证对象

目前，仅支持Web身份验证。然而，已经为以后使用服务身份验证方法实现铺平了框架。

use FootbridgeMedia\Accelo\Authentication\AuthenticationType;
use FootbridgeMedia\Accelo\Authentication\WebAuthentication;
use FootbridgeMedia\Accelo\Authentication\ServiceAuthentication;

// For web authentication
$authentication = new WebAuthentication();
$authentication->authType = AuthenticationType::Bearer;
$authentication->accessToken = "USER_ACCESS_TOKEN";
$authentication->refreshToken = "USER_REFRESH_TOKEN";

// For service authentication, use the below INSTEAD of the above
$authentication = new ServiceAuthentication();
$authentication->authType = AuthenticationType::Bearer;
$authentication->accessToken = "SERVICE_ACCESS_TOKEN";

客户端凭证对象

use FootbridgeMedia\Accelo\ClientCredentials\ClientCredentials;

$clientCredentials = new ClientCredentials();
$clientCredentials->deploymentName = "DEPLOYMENT_NAME";
$clientCredentials->clientID = "CLIENT_ID";
$clientCredentials->clientSecret = "CLIENT_SECRET";

注册身份验证和凭证

现在，将身份验证和凭证实例注册到Accelo对象。

$accelo->setAuthentication($authentication);
$accelo->setCredentials($clientCredentials);

API调用类型

根据本README和库版本，已实现所有可用过滤器、搜索和额外字段参数的API调用类型list。

列出公司

以下是一个使用提供的过滤器进行公司列表的示例。

use FootbridgeMedia\Accelo\Companies\Company;

// Set up a search query for the company results
$search = new Search();
$search->setQuery("Footbridge Media");

// Setup filters
$filters = new Filters();
$filters->addFilter(
    filterName:"standing",
    filterValue: "active",
);

// Perform the request
try{
    $requestResponse = self::$accelo->list(
        endpoint: "/companies",
        objectType: Company::class,
        filters: $filters,
        search: $search,
    );
}catch (\FootbridgeMedia\Resources\Exceptions\APIException $e) {
    print($e->getMessage());
} catch (\GuzzleHttp\Exception\GuzzleException $e) {
    // HTTP error from Guzzle
    print($e->getMessage());
}

/** @var Company[] $companies */
$companies = $requestResponse->getListResult();

foreach($companies as $company){
    printf("{$company->name}\n");
}

分页结果

Accelo对返回结果的最高限制是任何对象的100条记录。默认值为10。您可以使用Paginator对象指定要返回的页数和限制。如下所示。我们要求每次API调用返回的公司数量限制为15。此外，还有一个按名称升序排序的过滤器。

// ORDER BY filter
$filters = new Filters();
$filters->addFilter(
    filterName:"order_by_asc",
    filterValue: "name",
);

$paginator = new Paginator();
$paginator->setLimit(15);
$paginator->setPage(0); // Page 0 is the starting page

// Perform the request
$requestResponse = self::$accelo->list(
    endpoint: "/companies",
    objectType: Company::class,
    filters: $filters,
    paginator: $paginator,
);

/** @var Company[] $companies */
$companies = $requestResponse->getListResult();

foreach($companies as $company){
    printf("{$company->name}\n");
}

if ($requestResponse->hasMorePages){
    // Increment the paginator
    $paginator->incrementPage();
    
    // Repeat the same request
    $requestResponseNextPage = self::$accelo->list(
        endpoint: "/companies",
        objectType: Company::class,
        filters: $filters,
        paginator: $paginator,
    );
    
    /** @var Company[] $companies */
    $companiesFromNextPage = $requestResponseNextPage->getListResult();
}

如您在底部所见，您可以使用hasMorePages布尔标志来判断响应是否可能还有更多结果要返回。然后您可以使用incrementPage方法增加分页器。您可以使用与同一对象过滤器、字段和相同的分页器实例相同的API调用，但您将收到新的结果。

更新对象

以下是一个更新公司名称的示例。您可以使用此模式更新任何可更新的对象（问题、联系人等）。请求响应将包含更新对象的新的实例。

响应将遵循Accelo API仅返回默认字段的返回模式。additionalFields参数用于返回具有新返回对象的附加字段。

$companyIDToUpdate = 11; // ID of the company to update records of

$updateFields = new Fields();
$updateFields->addField(
    fieldName: "name",
    fieldValue:"Company's New Name!",
);

$requestResponse = self::$accelo->update(
    endpoint: "/companies/" . $companyID,
    objectType: Company::class,
    fields: $updateFields,
    additionalFields: null,
);

/** @var Company $companyUpdated */
$companyUpdated = $requestResponse->getUpdatedObject();

print($companyUpdated->name);

创建对象

创建对象的语法与更新现有对象类似。同样，使用additionalFields使API响应包含默认之外的已填充字段。

此示例将创建一个默认设置为非活动状态的新公司。

$creationFields = new Fields();
$creationFields->addField(
    fieldName: "name",
    fieldValue:"My New Company",
);

$creationFields->addField(
    fieldName: "standing",
    fieldValue: Standing::INACTIVE->value,
);

$additionalReturnFields = new AdditionalFields();
$additionalReturnFields->addField(
    fieldName:"standing",
);

$requestResponse = self::$accelo->create(
    endpoint: "/companies",
    objectType: Company::class,
    fields:$creationFields,
    additionalFields: $additionalReturnFields,
);

/** @var Company $newCompany */
$newCompany = $requestResponse->getCreatedObject();

print($newCompany->name);
print($newCompany->standing);

删除对象

删除对象不返回资源，因此不需要传递objectType。并非所有对象都可以删除。

self::$accelo->delete(
    endpoint: "/companies/1",
);

运行进度

目前，进度运行仅针对问题（票证）实现。runProgression是对象本身的一个方法。它接受依赖注入的Accelo对象。

通常，您会使用现有的对象来调用进度；然而，就像以下示例所示，您也可以创建一个具有填充ID的新空白对象，它将正常工作。

runProgression的响应将遵循Accelo API的返回模式，从API响应中返回已推进的对象。这意味着您可以为返回的对象提供additionalFields参数，使其包含不仅仅是默认字段。

// Create a dummy object with the desired ID to run a progression on
$issueID = 30155;
$issue = new Issue();
$issue->id = $issueID;

$progressionID = 100; // Get this from your Accelo deployment. It would be in the URL after you click a progression on a ticket type (NOT a status)

$additionalReturnFields = new AdditionalFields();
$additionalReturnFields->addField(
    fieldName: "status",
);

$requestResponse = $issue->runProgression(
    accelo: self::$accelo,
    progressionID: $testProgressionID,
    additionalFields:$additionalReturnFields,
);

/** @var Issue $progressedIssue */
$progressedIssue = $requestResponse->getProgressedObject();
print($progressedIssue->status); // Will be the new status after the progression is ran

修改API URL进行模拟服务器测试

您可以通过修改请求发送到的基本API URL和/或版本字符串来设置模拟服务器进行API测试。

Accelo对象有以下方法来设置和获取API基础URL（不包括附加的前斜杠）和API版本字符串（例如："v0"）

$accelo->setAPIBaseUrl("https://...");
$accelo->setAPIVersionString("v0");

// Getters
$accelo->getAPIBaseUrl();
$accelo->getAPIVersionString();

默认情况下，您不需要设置这些，因为它们为您定义了。如果您想覆盖这些，请在请求任何方法之前进行。此外，这自然会覆盖oAuth API端点。