README

JIRA 提供了 REST API，您可以使用这些 API 以编程方式与 JIRA 交互。此 API 客户端将帮助您通过 REST API 与 JIRA 交互。

许可证

MIT 许可证

JIRA REST API 参考文档

https://docs.atlassian.com/jira/REST/latest/

贡献

要创建新的端点 - 创建问题 或 创建拉取请求

安装

composer require madmis/jira-api 1.0.*

用法

$api = new madmis\JiraApi\JiraApi('https://:8080/', '/rest/api/2');

$auth = new madmis\JiraApi\Authentication\Basic('email@test.com', 'password');
$api->setAuthentication($auth);

$projectList = $api->project()->getProjects();

$project = $api->project()->getProject('MFTP');

$issue = $api->issue()->getIssue('MFTP-4');

// Issue result
array [
  'expand' => "renderedFields,names,schema,transitions,operations,editmeta,changelog"
  'id' => "10003"
  'self' => "https://:8080/rest/api/2/issue/10003"
  'key' => "MFTP-4"
  'fields' => { ... }
]

### 创建问题

$api = new madmis\JiraApi\JiraApi('https://:8080/', '/rest/api/2');

$auth = new madmis\JiraApi\Authentication\Basic('email@test.com', 'password');
$api->setAuthentication($auth);

// without mapping
$result = $api->issue()->createIssue('PROJ', 'summary', 1, ['description' => 'description']);

// Issue result
array [
  'id' => "10105"
  'key' => "PROJ-9"
  'self' => "http://127.0.0.1:8080/rest/api/2/issue/10105"
]

// with mapping
$result = $api->issue()->createIssue('PROJ', 'summary', 1, ['description' => 'description'], true);

// Issue result
class madmis\JiraApi\Model\Issue {
  protected $self => "http://127.0.0.1:8080/rest/api/2/issue/10104"
  protected $id => 10104
  protected $key => "PROJ-8"
  protected $labels => []
  protected $description => NULL
  protected $summary => NULL
  protected $updated => NULL
  protected $created => NULL
  protected $issueType => NULL
  protected $project => NULL
  protected $creator => NULL
  protected $reporter => NULL
  protected $assignee => NULL
  protected $status => NULL
}

### Tempo 工作日志（Tempo 时间表）

// This is default options, it is not required to set them.
// Set them only it Tempo REST API has another urn
$options = [
    'tempo_timesheets_urn' => '/rest/tempo-timesheets/3',
];
$api = new madmis\JiraApi\JiraApi('https://:8080/', '/rest/api/2', $options);

$auth = new madmis\JiraApi\Authentication\Basic('email@test.com', 'password');
$api->setAuthentication($auth);

$issue = $api->issue()->getIssue('MFTP-4');

// Tempo worklog result
array [
  array [
    'timeSpentSeconds' => 28800
    'dateStarted' => "2015-08-29T00:00:00.000"
    'comment' => "2323"
    'self' => "http://127.0.0.1:8080/rest/tempo-timesheets/3/worklogs/10000"
    'id' => 10000
    'author' => [ ... ]
    'issue' => [ ... ]
    'worklogAttributes' => [ ... ]
  ]
]

### 映射

$issue = $api->issue()->getIssue('MFTP-4', '*all', '', true);

// Result
class madmis\JiraApi\Model\Issue {
    protected $self => "https://:8080/rest/api/2/issue/10003"
    protected $id => 10003
    protected $key => "MFTP-4"
    protected $updated => class DateTime
    protected $issueType => class madmis\JiraApi\Model\IssueType
    protected $project => class madmis\JiraApi\Model\Project
    protected $creator => class madmis\JiraApi\Model\User
    protected $reporter => class madmis\JiraApi\Model\User
    protected $assignee => class madmis\JiraApi\Model\User
    protected $status => class madmis\JiraApi\Model\IssueStatus
  }

### 错误处理 每个客户端请求的错误都被包装到自定义异常 madmis\JiraApi\Exception\ClientException

class madmis\JiraApi\Exception\ClientException {
  private $request => class GuzzleHttp\Psr7\Request
  private $response => NULL
  protected $message => "cURL error 7: Failed to connect to 127.0.0.1 port 8080: Connection refused (see http://curl.haxx.se/libcurl/c/libcurl-errors.html)"
  ...
}

ClientException 包含原始 请求对象 和 响应对象（如果响应可用）

class madmis\JiraApi\Exception\ClientException {
  private $request => class GuzzleHttp\Psr7\Request 
  private $response => class GuzzleHttp\Psr7\Response {
    private $reasonPhrase => "Unauthorized"
    private $statusCode => 401
    ...
  }
  protected $message => "Client error: 401"
  ...  
}

因此，要处理错误请使用 try/catch

try {
    $issue = $api->issue()->getIssue('MFTP-4');
} catch (madmis\JiraApi\Exception\ClientException $ex) {
    // any actions (log error, send email, ...) 
}

运行测试

要运行测试，您需要安装 phpunit 和 behat。最简单的方法是通过 composer 完成。

composer install

运行单元测试

php vendor/bin/phpunit -c phpunit.xml.dist

运行 Behat 测试

要运行 Behat 测试，您需要安装 Jira。从示例配置文件 behat.yml.dist 创建配置文件

php vendor/bin/behat -c behat.yml