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并解析响应。当一切正常时，它会抛出以表示API错误或解析的响应数据。

这就全部了，它内部没有其他复杂逻辑：你决定要请求什么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获取特定字段的详细信息。你还需要通过响应进行搜索。但是，使用你可以这样做

$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()将始终返回相同对象的所有方法调用。

几乎所有的包装类都位于库内部都需要配置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对象，您只需提供一个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客户端实例。

更新issue

\Badoo\Jira\Issue 对象在内部属性中累积字段更改。这意味着，您对 $Issue 对象所做的任何更改都不会应用到实际的JIRA issue，直到您调用 ->save()。这允许您以紧凑的方式更新issue，将多个字段更改放入单个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

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

即使您在字段列表中可以看到它们，也并非所有字段都可以更改。这可能是由项目权限或issue编辑屏幕配置引起的。要检查当前用户是否可以通过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 对象。例如，出于您自己的原因，您在数据库中存储了一些issue信息：key、摘要和描述。您可以在这些数据上创建 \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的多个自定义字段时，使用单个 $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();

问题变更日志

issue更改日志的结构如下

    - 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[]

获取issue的更改历史

如果您已经有了一个用于操作的issue对象，只需使用 ->getHistory() 方法即可。

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

$History = $Issue->getHistory();

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

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

History类有一些有用的方法，可以帮助您解决大多数常见任务

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

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

Badoo JIRA API客户端的其他实例

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

对于自定义字段和问题对象，您有2种初始化方式：使用静态方法（例如 ::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 的API错误。
::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请求：您可以选择几种初始化问题对象的方法，这将对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(<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() 方法在Issue对象从API加载数据后被调用。这是通知所有现有的绑定自定义字段对象字段值可能已更新的方式。

badoo / jira-client

维护者

详细信息