README

使用Laravel 5.4+执行Jira API的各种操作

该包的目的是使与API的通信更简单。默认情况下，请求的响应不会进行任何修改。通过创建自己的实现或使用包中提供的简单助手，您可以以您喜欢的方式集成Jira。

安装

要获取最新版本的 laravel-jira-rest-client，请运行以下命令

composer require masterarrow/laravel-jira-rest-client

请注意，并非所有方法都已实现。

Laravel 5.5 使用包自动发现，因此不需要您手动添加 ServiceProvider。

Laravel 5.4

如果您不使用自动发现，请将 ServiceProvider 添加到 config/app.php 中的 providers 数组

<?php

'providers' => [
    // ...

    Atlassian\JiraRest\JiraRestServiceProvider::class,
],

还要在您的 config/app.php 文件中找到 Aliases 键并注册 Facade

<?php

'aliases' => [
    // ...

    'Jira' => Atlassian\JiraRest\Facades\Jira::class,
],

使用发布命令将包配置复制到本地配置

php artisan vendor:publish --provider="Atlassian\JiraRest\JiraRestServiceProvider"

使用来自 config/atlassian/jira.php 的JIRA变量更新 .env，以使用您的正确凭据。

使用方法

此包的核心直接反映了Jira API，这意味着所有请求类都不会格式化您从API获取的响应。这个决定是为了使包更具通用性，允许用户按照自己的意愿处理请求的响应。

例如，要获取特定的任务，您可以执行以下操作

<?php

$request = new \Atlassian\JiraRest\Requests\Issue\IssueRequest;
$response = $request->get('ISSUE-3'); // Array

参数

通过请求发送参数有两种方式

1. 使用数组
2. 创建一个实现了 \Illuminate\Contracts\Support\Arrayable 的类

使用数组时，您可以创建如下请求

<?php

use Atlassian\JiraRest\Requests\Project;

/** @var \Atlassian\JiraRest\Requests\Project\ProjectRequest $request */
$request = app(Project\ProjectRequest::class);

$response = $request->search([
    'maxResults' => 10,
    'startAt' => 0
]);

$output = \json_decode($response->getBody()->getContents(), true);

您可以选择创建一个实现了 \Illuminate\Contracts\Support\Arrayable 的类，该类的 toArray 方法将返回请求的参数。或者，您可以扩展 \Atlassian\JiraRest\Requests\AbstractParameters 以“填充”或“覆盖”类内设置的参数。

使用类可以在多个地方执行请求时确保每次请求的值都相同。

身份验证

因此Jira支持多种身份验证方式。默认情况下是基本身份验证。

基本身份验证

要使用基本身份验证，您需要将以下内容添加到您的 .env

JIRA_USER=
JIRA_PASS=

其中凭据与您要登录的用户相同。

如果您希望每个用户都有自己的凭据，您需要在运行时将这些凭据设置在配置中

<?php

config('atlassian.jira.auth.basic.username', 'info@example.com');
config('atlassian.jira.auth.basic.password', 'secret');

会话

另一个实现是会话，但该包尚未实现。

OAuth

要使用 OAuth 2.0，您需要将以下内容添加到您的 .env 文件

JIRA_HOST=https://api.atlassian.com/ex/jira/
JIRA_AUTHENTICATION=oauth2

用于用户认证

$url = 'https://yuor-web-site/callback-url';

$scopes = ['read:jira-user', 'read:jira-work', ...];

// $clientId and $secret you can get from .env file

$auth = new OAuthHandler($clientId, $secret, $url, $user-unique-identifier, $scopes);
$auth->authenticate();

之后，用户将被自动重定向到 Jira 进行身份验证。在您的 callback-url 路由

$params = $request->only('state', 'code');
$data = $this->authHandler->getAccessTokens($params);

// $data['cloudId']);
// $data['accessToken']);
// $data['refreshToken']);
// $data['expires']);

使用 OAuth 2.0 获取任务

$response = $auth->issue()->->get('ISSUE-3');

刷新访问令牌

$data = $auth->refreshAccessTokens($clientId, $secret, $refreshToken);

// $data['accessToken']);
// $data['refreshToken']);
// $data['expires']);

助手（已弃用）

由于您大部分时间都不想自己编写请求，因此有一些有用的助手可以帮助您与API通信。

要获取单个任务，您可以使用以下代码

$issue = jira()->issue('ISSUE-3')->get();

或者如果您喜欢，可以使用 facade

$issue = \Jira::issue('ISSUE-3')->get();

弃用大多数助手，因为为所有类编写助手需要太多的维护

中间件

要更改用于请求的 Guzzle 客户端，您可以添加“中间件”来更改选项。

有多种方式可以添加中间件。

使用配置

您可以使用配置文件 config/atlassian/jira.php 中的 client_options 数组来设置一个或多个中间件。

例如

<?php

'client_options' => [
    'auth' => \App\Services\Jira\Middleware\LogRequestMiddleware::class,
],

这些中间件可以命名，也可以直接使用值

通过使用 addMiddleware 方法

当您有一个 AbstractRequest 实例时，可以通过调用 addMiddlware 来添加多个中间件，如下所示

<?php

use Atlassian\JiraRest\Requests;

/** @var \Atlassian\JiraRest\Requests\ServerInfoRequest $request */
$request = app(Requests\ServerInfoRequest::class);
$request->addMiddleware(\App\Services\Jira\Middleware\LogRequestMiddleware::class);

伪装

要通过 Jira 请求伪装用户，您必须在您的 .env 文件中设置 JIRA_IMPERSONATE=true。

一旦启用伪装，Laravel 将默认使用认证用户的 name。然而，您也可以通过将用户名发送到中间件的构造函数来手动伪装用户。为此，您需要手动注册中间件并传递用户信息。