README

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

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

安装

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

composer require rjvandoesburg/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');

所有响应都是 \GuzzleHttp\Psr7\Response 的实例，了解更多，因此要获取 JSON 响应，您可以这样做

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

这会返回类似于在 API 中看到的响应

参数

可以通过两种方式在请求中发送参数

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，您需要添加 Guzzle 的 OAuth 包：composer require guzzlehttp/oauth-subscriber

最后是 OAuth 选项，请在继续之前先阅读 Jira 文档https://developer.atlassian.com/server/jira/platform/oauth/

阅读完之后，您需要在 Jira 的侧创建一个应用程序（如该页面上解释的那样）并在您的 .env 中设置凭证。

JIRA_HOST={url of your Jira instance}
JIRA_CONSUMER_KEY={as set in Jira}
JIRA_PRIVATE_KEY={full path location to your key used for authentication}

这些凭证足以与 API 通信进行登录。在 src/Http/Controllers/OAuthController.php 中，您可以找到如何进行 'oauth' 舞蹈的说明。

通过在 .env 文件中设置 JIRA_OAUTH_ROUTES=true，可以启用此控制器。一旦启用，您就可以导航到 /atlassian/jira/oauth/access，这将带您转到 Jira 以授予访问权限。

完成此操作后，您将在会话中找到 oauth 令牌（flashed），这将允许您从 Jira 请求资源。这允许您决定将密钥存储在哪里，例如数据库或会话。或者，您可以捕获事件 \Atlassian\JiraRest\Events\OAuth\AccessTokensReceived 以处理令牌。您也可以将这些凭证设置在 .env 中，这样您在未来就不需要再次进行身份验证，因为令牌有效期为 5 年（根据 Jira）

JIRA_OAUTH_TOKEN=
JIRA_OAUTH_TOKEN_SECRET=

辅助工具（已弃用）

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

要获取单个问题，您可以使用以下代码

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

或者如果您更喜欢使用外观

$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。但是，您还可以手动通过将用户名发送到中间件的构造函数来伪装用户。为此，您需要手动注册中间件并传递用户。

JIRA 伪装设置

1. 遵循 Jira 文档 以生成 RSA 公钥/私钥对。
2. 转到 Jira --> 应用链接（管理员）
3. 使用您的服务器 URL 创建一个新的链接
4. 忽略“无响应”警告
5. 在所有字段中输入任何内容，并保持“创建传入链接未选中”。Jira 在设置应用链接时有一些奇怪的行为。如果您现在创建传入链接，您将无法访问双因素身份验证（伪装）。
6. 单击继续（忽略警告）。这将创建您的新应用链接。
7. 编辑此链接（注意，即使在创建时添加了虚拟信息，也没有传出信息）。
8. 现在您可以输入 OAuth 和伪装设置的所有信息（允许双因素 OAuth）。

待办事项

• 实现缺失的请求
• 中间件
• 更好的 README
• 会话身份验证
• 更改请求之前的方法（全局对每个请求，以及针对特定请求的可能性）
• 测试