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库中的封装类都需要配置API客户端才能工作。它总是作为任何封装类的静态方法或构造函数的最后一个参数接收，并且如果没有提供值，则默认为'全局'客户端。

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

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

注意：本文档中所有与JIRA交互的示例，均假设您已配置了'全局'客户端对象。这就是为什么我们不将初始化的JIRA API客户端传递给所有的Issue、CustomField和其他对象。

我们保留向所有包装器提供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请求中。$Issue对象将继续返回旧的字段值，直到您使用->save()将更改发送到JIRA。

$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 发送请求。这允许您在需要时控制 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 加载。只有 JIRA API 提供的默认数据将被加载。

当您需要问题历史记录时，\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 对象。这意味着字段

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

将有不同的 \Badoo\Jira\Issue 对象，即使它们引用的是单个JIRA问题。

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

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

这意味着您能够将多个自定义字段更改“堆叠”在一个 $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 加载数据后被调用。这是通知所有现有的绑定自定义字段对象字段值可能已更新的方式。

sc0/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

在子类中使用的函数

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