README

简介
快速开始
文档
高级主题

简介

这是Badoo JIRA REST客户端。它包含了一组包装类，用于最常见的API对象：问题、组件等。

这使得代码编写更加容易，因为你的IDE会提供自动完成功能。

你也可以为自定义字段生成很多类，以便在PHP代码中直接获取你自己的JIRA安装的文档。

快速开始

安装

composer require badoo/jira-client

初始化客户端

$Jira = \Badoo\Jira\REST\Client::instance();
$Jira
    ->setJiraUrl('https://jira.example.com/')
    ->setAuth('user', 'token/password');

创建新问题

$Request = new \Badoo\Jira\Issue\CreateRequest('SMPL', 'Task');

$Request
    ->setSummary('Awesome issue!')
    ->setDescription('description of issue created by Badoo JIRA PHP client')
    ->setLabels(['hey', 'it_works!'])
    ->addComponent('Other');

$Issue = $Request->send();

print_r(
    [
        'key'           => $Issue->getKey(),
        'summary'       => $Issue->getSummary(),
        'description'   => $Issue->getDescription(),
    ]
);

获取问题

$Issue = new \Badoo\Jira\Issue('SMPL-1');

print_r(
    [
        'key'           => $Issue->getKey(),
        'summary'       => $Issue->getSummary(),
        'description'   => $Issue->getDescription(),
    ]
);

更新问题

$Issue
    ->setSummary('Awesome issue!')
    ->setDescription('Yor new description for issue')
    ->edit('customfield_12345', <value for field>);

$Issue->save();

删除问题

$Issue = new \Badoo\Jira\Issue('SMPL-1');
$Issue->delete();

文档

注意：本文档中所有与JIRA交互的示例都考虑你已配置了'全局'客户端对象。

阅读上述配置客户端部分，了解如何进行配置。

客户端和ClientRaw

JIRA API客户端分为两个部分

API最简单的接口：Badoo\Jira\REST\ClientRaw

它可以请求API并解析响应。如果一切顺利，则抛出Badoo\Jira\REST\Exception异常，或者在解析响应数据时抛出。

这就是全部，它内部没有其他复杂逻辑：你决定请求哪个URI，发送哪种HTTP请求（GET、POST等），以及发送哪些参数。

将ClientRaw视为PHP curl的智能包装器。

$RawClient = new \Badoo\Jira\REST\ClientRaw('https://jira.example.com');
$RawClient->setAuth('user', 'token/password');

$fields = $RawClient->get('/field');
print_r($fields);

结构化客户端Badoo\Jira\REST\Client

它分为几个部分，每个部分对应API方法的每个前缀：例如/issue、/field、/project等。每个部分都有对接受参数的最受欢迎的API方法的绑定。

目的是让你免于记住常见操作的URI和HTTP请求类型。它使你的IDE能够提供关于可用API方法和可以提供给每个方法的选项的提示。

某些部分也缓存API响应，并具有用于最常见操作的'合成'方法。例如，你只能通过API使用ID获取特定字段的详细信息。你还需要在响应中搜索。但是，使用Badoo\Jira\REST\Client，你可以这样做

$Client = new \Badoo\Jira\REST\Client('https://jira.example.com/');
$Client->setAuth('user', 'password/token');

$FieldInfo = $Client->field()->get('summary');
print_r($FieldInfo);

当你无法在结构化客户端中找到所需内容时，你仍然可以访问其中的原始客户端以执行所需的所有操作

$Client = \Badoo\Jira\REST\Client::instance();
$response = $Client->getRawClient()->get('/method/you/wat/to/request', [<parameters]);

结构化客户端还有一个'全局'客户端对象。该对象可以通过instance()静态方法访问

$Client = \Badoo\Jira\REST\Client::instance();

底层是'new Badoo\Jira\REST\Client()',但::instance()将始终为所有方法调用返回相同的对象。

几乎所有Badoo\Jira库中的包装类都需要配置的API客户端才能工作。它始终作为任何静态方法或包装器构造函数的最后一个参数接收，并且默认情况下始终为'全局'客户端，除非提供了值。

一旦你配置了全局客户端，你不需要将API客户端提供给所有初始化的包装器。它们会自己获取。

\Badoo\Jira\REST\Client::instance()
    ->setJiraUrl('https://jira.example.com')
    ->setAuth('user', 'password/token');

注意：文档中所有随后的示例，与任何与JIRA交互有关，都考虑你已配置了'全局'客户端对象。这就是为什么我们不向所有Issue、CustomField和其他对象传递初始化的JIRA API客户端。

将提供API客户端的方式作为参数传递给所有包装器的唯一原因是为了让您能够使用一段代码与多个JIRA安装进行交互。例如，如果您想同时处理您的预发布和生产实例

$Prod = new \Badoo\Jira\REST\Client('https://jira.example.com/');
$Prod->setAuth('user', 'password/token');

$Staging = new \Badoo\Jira\REST\Client('https://staging.jira.example.com/');
$Staging->setAuth('user', 'password/token');

$ProdIssue = new \Badoo\Jira\Issue('SMPL-1', $Prod);
$StagingIssue = new \Badoo\Jira\Issue('SMPL-1', $Staging);

// ...

Badoo\Jira\Issue类

获取 \Badoo\Jira\Issue 实例

要获取一个问题对象，您可以只提供一个问题键来创建它。

$Issue = new \Badoo\Jira\Issue('SMPL-1');

这相当于

$Client = \Badoo\Jira\REST\Client::instance();
$Issue = new \Badoo\Jira\Issue('SMPL-1', $Client);

如果您愿意，可以实例化另一个API客户端并将其提供给 \Badoo\Jira\Issue 构造函数。当您有多个JIRA实例并希望从单段代码中处理它们时，这可能很有用。请参阅文档中的客户端和ClientRaw 部分，了解如何配置API客户端实例。

更新问题

\Badoo\Jira\Issue 对象会在内部属性中累积字段更改。这意味着，您对 $Issue 对象所做的任何更改都不会应用到实际的JIRA问题，直到您调用 ->save()。这允许您以紧凑的方式更新问题，将多个字段更改放入单个API请求中。在您通过 ->save() 将更改发送到JIRA之前，$Issue 对象将继续返回旧的字段值。

$Issue = new \Badoo\Jira\Issue('SMPL-1');
$Issue
    ->setSummary('new summary')
    ->setDescription('new description')
    ->edit('customfield_12345', 'new custom field value');

$Issue->getSummary(); // will return old issue summary, not the one you tried to set 3 lines of code ago

$Issue->save(); // makes API request to JIRA, updates all 3 fields you planned

$Issue->getSummary(); // will return new issue summary, as expected

检查我们是否可以编辑字段

即使您在字段列表中显示它们，也不是所有字段都可以更改。这可能是由于项目权限或问题编辑屏幕配置引起的。要检查当前用户是否可以通过API更新字段，请使用 ->isEditable();

$Issue = new \Badoo\Jira\Issue('SMPL-1');
if ($Issue->isEditable('summary')) {
    // we can edit summary
} else {
    // we can't edit summary
}

在部分字段数据上初始化 \Badoo\Jira\Issue 对象

您还可以在只包含一些字段的数据上创建 \Badoo\Jira\Issue 对象。例如，出于您自己的原因，在您的数据库中存储一些问题信息：键、摘要和描述。您可以在这些数据上创建 \Badoo\Jira\Issue 对象，而不会破坏对象逻辑：当您需要时，它仍然会从API加载数据。

// Consider you get this data from your database:
$db_data = [
    'key' => 'SMPL-1',
    'summary' => 'summary of example issue',
    'description' => 'description of example issue',
];

// First, create an \stdClass object to mimic API response:
$IssueInfo = new \stdClass();
$IssueInfo->key = $db_data['key'];

$IssueInfo->fields = new \stdClass();
$IssueInfo->fields->summary = $db_data['summary'];
$IssueInfo->fields->description = $db_data['description'];

// Now we can create an issue object. It will store key, summary and description field values in internal cache
// When you need some additional data, e.g. creation time or assignee - object will still load it from API on demand.
$Issue = \Badoo\Jira\Issue::fromStdClass($IssueInfo, ['key', 'summary', 'description']);

自定义字段

您可以使用存储在此存储库中的特殊生成器生成自定义字段。有关更多信息，请参阅 CFGenerator 子目录并打开 README.md 文件。您将在那里找到关于生成器的快速入门和详细文档。

在本节中，我们假设您已经创建了一个用于常规自定义字段的类，该类可在JIRA中直接使用：“复选框”、“数字字段”、“单选按钮”、“选择列表（单选）”等。

让我们假设您在 \Example\CustomField 命名空间内创建了自定义字段类（或类）。

字段值：获取、检查、设置

$MyCustomField = \Example\CustomFields\MyCustomField::forIssue('SMPL-1'); // get field value from JIRA API

$field_value = $MyCustomField->getValue();
$field_is_empty = $Value->isEmpty(); // true when field has no value

if ($Value->isEditable()) {
    $MyCustomField->setValue($MyCustomField::VALUE_AWESOME); // consider this is a select field
    $MyCustomField->save(); // send API request to update field value in JIRA
}

在单个问题上使用多个自定义字段

当您需要处理同一问题的多个自定义字段时，使用单个 $Issue 对象是更好的做法

$Issue = new \Badoo\Jira\Issue('SMPL-1');

$MyCustomField1 = new \Example\CustomFields\MyCustomField1($Issue);
$MyCustomField2 = new \Example\CustomFields\MyCustomField2($Issue);

$MyCustomField1->setValue('value of first field');
$MyCustomField2->setValue('value of second field');

$Issue->save();

问题变更日志

问题更改日志具有以下结构

    - changelog record 1 (issue update event 1)
        - changelog item 1 (field 1 changed)
        - changelog item 2 (field 2 changed)
        - ...
    - changelog record 2 (issue update event 2)
        - changelog item 1 (field 1 changed)
        - ...

有一个特殊的 \Badoo\Jira\History 类专门用于处理这些数据。它为更改日志中的每条信息使用自己的包装器

\Badoo\Jira\Issue\History
    \Badoo\Jira\Issue\HistoryRecord[]
        \Badoo\Jira\Issue\LogRecordItem[]

获取问题的更改历史

如果您已经有了要处理的问题对象，只需使用 ->getHistory() 方法即可。

$Issue = new \Badoo\Jira\Issue('SMPL-1');

$History = $Issue->getHistory();

如果没有，只需使用静态方法创建对象。

$History = \Badoo\Jira\Issue\History::forIssue('SMPL-1');

历史类有一些有用的方法来帮助您解决大多数常见任务

跟踪字段更改，
计算状态中的时间，
获取问题的最后更改，
获取特定问题字段的最后更改，
...等等

使用您的IDE自动完成功能发现其方法，它们可能很有用！

Badoo JIRA API客户端的其他实例

大多数包装器类，例如 User、Status、Priority 等，都具有在需要时透明地从API加载数据的能力。

至于 CustomFields 和 Issue 对象，您有两种初始化方式：使用静态方法（例如 ::get()）和常规构造函数

$User = new \Badoo\Jira\User(<user name>);

$User = \Badoo\Jira\User::byEmail(<user email>);

它们中的大多数都有简写静态方法

$users = \Badoo\Jira\User::search(<pattern>); // looks for all users with login, email or display name similar to pattern
$Version = \Badoo\Jira\Version::byName(<project>, <version name>); // looks for version with specific name in project
$components = \Badoo\Jira\Component::forProject(<project>); // lists all components available in project

这些方法名称具有类似的结构。为了方便，我们决定遵循以下约定

::search() 静态方法用于实例的多条件搜索。例如，在 \Badoo\Jira\Issue::search() 中使用复杂的 JQL 查询，或者在 \Badoo\Jira\User::search() 中，JIRA 会检查多个用户属性以找到您需要的用户。
::get() 静态方法用于通过其 ID 立即请求 API 获取单个对象。这允许您在需要时控制在哪里获取 \Badoo\Jira\REST\Exception。
::by() 静态方法提供您通过某些单一标准识别的单个或多个对象。

示例
- \Badoo\Jira\User::byEmail() 根据电子邮件地址返回一个 JIRA 用户。
- \Badoo\Jira\Version::byName() 根据名称返回一个 JIRA 版本。
::for() 静态方法查找与实例以某种方式相关联的所有项。

示例
- \Badoo\Jira\CustomField::forIssue() 返回与问题相关联的自定义字段对象。
- \Badoo\Jira\Version::forProject() 返回在特定项目中创建的所有版本。
::fromStdClass() 方法由所有包装类用于从 API 数据初始化。如果您使用 \Badoo\Jira\REST\ClientRaw 等方式从 API 获取了一些信息，您仍然可以使用类型化的对象而不是原始的 \stdClass' 对象来操作。

示例
```
$PriorityInfo = \Badoo\Jira\REST\ClientRaw::instance()->get('priority/<priority ID>');
$Priority = \Badoo\Jira\Issue\Priority::fromStdClass($PriorityInfo);
```

作为活动记录并且知道如何从 API 加载数据以及如何设置的类与 \Badoo\Jira\Issue 使用的行为相同：它们在对象内部积累更改，并在 ->save() 方法调用时将其推送到 API。

高级主题

管理API请求

使用 'new' 指令创建 $Issue 对象后，它只包含问题密钥和客户端。它只有在您第一次尝试获取某些字段时才会加载数据。

$Issue = new \Badoo\Jira\Issue('SMPL-1'); // no request to API here, just an empty object is returned
$Issue->getSummary(); // causes request to JIRA API

当 $Issue 对象自己从 API 加载数据时，它不会选择要加载的字段。这会增加 API 响应时间，并加载大量不是“现在”所需的关于问题摘要的数据。但是，由于 \Badoo\Jira\Issue 没有关于它将获得多少额外的 ->get() 调用的想法，所以最好一次性加载所有信息，而不是在需要摘要时请求 API，然后在需要描述、状态、优先级等时再请求。

我们比较了 JIRA 加载数据并将其发送到客户端所需的时间（请参阅 examples/measure-load-time.php）。它可能因安装而异，但几乎总是（据我们所知——总是）'获取所有字段' 请求比 3 个 '获取单个字段' 请求更有效，而且通常比 2 个更有效。

Get single field time: 0.42949662208557
Get all fields time: 0.84061505794525

您可以通过使用类的一个静态方法在创建新实例后立即进行 API 调用。

$Issue = \Badoo\Jira\Issue::byKey('SMPL-1'); // causes request to JIRA API
$Issue->getSummary(); // no request here, object already has all the data on issue

唯一由 \Badoo\Jira\Issue 管理的是 'expand'。JIRA API 允许您通过 'expand' 参数请求各种部分信息。例如，在大多数情况下，您不需要字段的渲染 HTML 代码或问题更改日志。默认情况下，当您调用 ->get() 时，这些数据不会被 \Badoo\Jira\Issue 加载。

当您需要问题历史记录时，\Badoo\Jira\Issue 对象必须再次请求 API 以获取它。它还将提供具有更新字段信息的对象，并且如果您在最后一次调用 API 以来它们已更改，您将获得更新的摘要、描述等。

在大多数情况下，当您处理单个问题时，您不需要担心 \Badoo\Jira\Issue 类的内部逻辑，但是理解是必要的，以便在同时处理大量问题时有效地管理 API 请求：您可以选择几种初始化 Issue 对象的方式，这将对 API 请求的数量和有效性产生不同的副作用。

例如，如果您知道您只需要大量问题的摘要和描述，您可以仅请求它们。这将显着减少 API 响应时间。

// load only summary and description for the latest 1000 issues in project 'SMPL'.
$issues = \Badoo\Jira\Issue::search('project = SMPL ORDER BY issuekey DESC', ['summary', 'description']);

foreach($issues as $Issue) {
    $Issue->getDescription(); // this will not make \Badoo\Jira\Issue to silently request JIRA API in background

    $Issue->getPriority(); // but this - will. $Issue object has no status information in cache.
}

JIRA 加载问题历史可能相当困难。这会显著影响API响应时间，尤其是当您有很长的变更日志时。这是您可以通过告诉 \Badoo\Jira\Issue 您需要什么来进行优化的东西。

// load latest 100 issues from project 'SMPL'
$issues = \Badoo\Jira\Issue::search(
    'project = SMPL ORDER BY issuekey DESC',
    [],
    [\Badoo\Jira\REST\Section\Issue::EXP_CHANGELOG],
    100
);

foreach ($issues as $Issue) {
    $description = $Issue->getDescription(); // this will not cause API request
    $status_changes = $Issue->getHistory()->trackField('status'); // this will not cause API request too!
}

不幸的是，您不能同时使用 $fields 和 $expand 参数。这是因为 \Badoo\Jira\Issue 缓存的内部逻辑，这种组合将导致缓存损坏。如果这个问题显示为有问题，我们将未来修复它。

使用自定义字段管理API请求

您可以通过几种方式实例化自定义字段对象。对于 \Badoo\Jira\Issue 的实例化，它们在初始化和值更新所需的API请求方面有所不同。

$MyCustomField = \Example\CustomFields\MyJIRACustomField::forIssue('SMPL-1');

// The example above is equivalent to:
$Issue = \Badoo\Jira\Issue::byKey('SMPL-1', ['key', \Example\CustomFields\MyJIRACustomField::ID]);
$MyCustomField = new \Example\CustomFields\MyJIRACustomField($Issue);

在两个示例中，我们创建的 CustomField 对象在底层都有一个 \Badoo\Jira\Issue 对象。差异会在您开始处理一个问题的多个自定义字段时显现出来。

使用静态方法 ::forIssue() 进行初始化始终会在底层创建一个新的 \Badoo\Jira\Issue 对象。这意味着即使它们指向单个JIRA问题，字段也将具有不同的 \Badoo\Jira\Issue 对象。

$MyCustomField1 = \Example\CustomFields\MyFirstCustomField::forIssue('SMPL-1');
$MyCustomField2 = \Example\CustomFields\MySecondCustomField::forIssue('SMPL-1');

所有自定义字段都使用 \Badoo\Jira\Issue 作为管理它们值的工具：它们通过它加载数据并使用 Issue 提供的接口来编辑自己。

当您调用 $CustomField->setValue() 时，实际上它与 $Issue->edit(<自定义字段ID>, <新字段值>); 类似。

这意味着您可以将多个自定义字段更改“堆叠”在单个 $Issue 对象中，以一次发送到API，使API交互更加优化。

这意味着您可以在一个 $Issue 对象中“堆叠”多个自定义字段更改，然后只向API发送一次更新，使API交互更加优化。

$Issue = \Badoo\Jira\Issue::byKey('SMPL-1'); // causes API request to get all issue fields

$MyCustomField1 = new \Example\CustomFields\MyFirstCustomField($Issue);
$MyCustomField2 = new \Example\CustomFields\MySecondCustomField($Issue);
// other custom fields initialization

$MyCustomField1->setValue('new value'); // no API requests here. Field value in JIRA remains the same
$MyCustomField2->setValue($MyCustomField2::VALUE_CHANGED); // no API requests here too.
// other custom fields changes

$Issue->save(); // API request to JIRA with field updates

// Now JIRA issue has new field values and one new changelog record.
// You can also use $MyCustomField2->save(); - it is the same,
// but with $Issue->save(); it is more clear what is happening

使用其他类管理API请求

其他类，如状态、优先级和用户，有特殊的 ::get 静态方法，该方法的效应与常规构造函数类似，但会影响对API的请求。

$Status = new \Badoo\Jira\Issue\Status(<status ID>); // no request to API here
$Status->getName(); // requests API in background. This is where exception will be thrown on errors.

// ...

$Status = \Badoo\Jira\Issue\Status::get(<status ID>); // request to API here. This is where exception will be thrown on errors.

扩展Badoo\Jira\Issue

\Badoo\Jira\Issue 是关于抽象JIRA实例的。它不知道您经常使用的自定义字段、您经常转换的状态等。对于您经常执行的操作，拥有自己的快捷方式会方便得多。

为此，我们建议您创建自己的 Issue 类来扩展 \Badoo\Jira\Issue 功能，并添加您自己的方法。

例如，您可能希望通过一个调用轻松关闭问题，并将解决状态设置为某个特殊值。下面是步骤

namespace Example;

class Issue extends \Badoo\Jira\Issue {
    public function markDone() : Issue
    {

        return $this;
    }
}

// ...

$Issue = new \Example\Issue('SMPL-1');
$Issue->markDone();

您可能想扩展 \Badoo\Jira\Issue\CreateRequest 以返回您的 Issue 对象而不是原始对象

namespace Example;

class CreateRequest extends \Badoo\Jira\Issue\CreateRequest {
    public function create() : \Badoo\Jira\Issue
    {
        $Issue = parent::create();

        $IssueInfo = new \stdClass();
        $IssueInfo->id = $Issue->getId();
        $IssueInfo->key = $Issue->getKey();

        return \Example\Issue::fromStdClass($IssueInfo, ['id', 'key']);
    }
}

子类中要使用的方法

这里有一段代码示例。它们比一大堆文字更有信息量。

namespace Example;

class Issue extends \Badoo\Jira\Issue {
    public function getSomeDataFromRawApiResponse()
    {
        /** @var \stdClass $IssueInfo - contains an issue data obtained from JIRA API,
                                        returned from \Badoo\Jira\ClientRaw 'as-is'. */
        $IssueInfo = $this->getBaseIssue();

        $issue_key = $IssueInfo->key;
        $issue_id = $IssueInfo->id;
        $self_link = $IssueInfo->self;
        $summary = $IssueInfo->fields->summary;
        // ...
    }

    public function getFieldUsingCache() : \stdClass
    {
        return $this->getFieldValue('customfield_12345');
        // this is equivalent to
        //  $this->getBaseIssue()->fields->customfield_12345;
        // but will not cause API request when you use partial field inititialization
    }

    public function getMyCustomField() : \Example\CustomFields\MyCustomField
    {
        return $this->getCustomField(\Example\CustomFields\MyCustomField::class);
        // this will also not cause API request when you use partial field initialization, but also return you
        // the same object of \Example\CustomFields\MyCustomField each time you use the method
    }
}

编写自己的自定义字段基类

所有自定义字段都应该继承自 \Badoo\Jira\Issue\CustomFields\CustomField 类或其子类。自定义字段基类的最简单示例是 \Badoo\Jira\CustomFields\TextField 和 \Badoo\Jira\CustomFields\NumberField。

还有一些额外的特殊方法您应该知道

$this->getOriginalObject() - 获取由JIRA API提供的字段值。
$this->dropCache() - 丢弃对象内部缓存的全部数据，例如丢弃缓存的字段值。

getOriginalObject() 方法请求当前字段值的绑定 Issue 对象。它将值缓存在当前对象中，可以连续多次调用它。这不会导致多个API请求。我们期望您始终使用此方法，而不是 $this->Issue->getFieldValue()，当您编写直接从 \Badoo\Jira\Issue\CustomFields\CustomField 继承的自定义包装器时。

dropCache() 方法旨在丢弃对象内部缓存的有关字段值的全部数据。如果您计划在自定义类中使用内部属性，不要忘记重新定义 dropCache() 方法，以便清除字段值。

dropCache() 方法在绑定的 Issue 对象从API加载数据时被调用。这是通知所有现有的绑定自定义字段对象字段值可能已更新的方式。

egorkonopka / jira-client

维护者

详细信息

README

简介

快速开始

安装

初始化客户端

创建新问题

获取问题

更新问题

删除问题

文档

客户端和ClientRaw

API最简单的接口：Badoo\Jira\REST\ClientRaw

结构化客户端Badoo\Jira\REST\Client

Badoo\Jira\Issue类

获取 \Badoo\Jira\Issue 实例

更新问题

检查我们是否可以编辑字段

在部分字段数据上初始化 \Badoo\Jira\Issue 对象

自定义字段

字段值：获取、检查、设置

在单个问题上使用多个自定义字段

问题变更日志

获取问题的更改历史

Badoo JIRA API客户端的其他实例

高级主题

管理API请求

使用自定义字段管理API请求

使用其他类管理API请求

扩展Badoo\Jira\Issue

子类中要使用的方法

编写自己的自定义字段基类