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 交互相关的后续示例都假设你已配置了 '全局' 客户端对象。这就是为什么我们不会将初始化的 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请求中。在您使用 ->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() 用于实例的多条件搜索。例如，对于使用复杂 JQL 查询的 \Badoo\Jira\Issue::search() 和尝试根据多个用户属性找到用户的 \Badoo\Jira\User::search() 都适用。
静态方法 ::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对象。这意味着字段将具有不同的\Badoo\Jira\Issue对象，即使它们引用的是同一个JIRA问题。

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

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

当你调用$CustomField->setValue()时，实际上它与$Issue->edit(<custom field id>, <new field value>);相似。

这意味着你能够在一个$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() 方法由绑定到的问题对象在从API加载数据时调用。这是通知所有现有的绑定自定义字段对象字段值可能已更新的方式。

admhome / badoo-jira-client-modified

维护者

详细信息

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

子类中要使用的方法

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