README

创建JIRA和Confluence插件的便捷方式。

版本兼容性

入门指南

安装

使用Composer安装依赖项

$ composer require "brezzhnev/atlassian-connect-core"

通过向 app\Http\Kernel.php 添加以下行注册 路由中间件 jwt

'jwt' => \AtlassianConnectCore\Http\Middleware\JWTAuth::class

在 config/auth.php 中将身份验证驱动程序设置为 jwt

'guards' => [
    'web' => [
        'driver' => 'jwt',
        'provider' => 'users',
    ],
...

在 config/auth.php 的 providers 部分设置模型类

'providers' => [
    'users' => [
        'driver' => 'eloquent',
        'model' => \AtlassianConnectCore\Models\Tenant::class,
    ],
...

在 app/Providers/EventServiceProvider.php 中注册订阅者

/**
 * The subscriber classes to register.
 *
 * @var array
 */
protected $subscribe = [
    \AtlassianConnectCore\Listeners\PluginEventSubscriber::class
];

配置数据库并运行

php artisan migrate
php artisan plugin:install

命令 php artisan plugin:install 将发布配置、视图和资源，您可以根据需要更改。

此外，它将创建用于本地测试和开发的“虚拟”租户，无需在真实的JIRA或Confluence实例上安装插件。

作为插件发布

如果您的应用程序在请求URL https://:8000/atlassian-connect.json 时返回插件描述符，则意味着您即将成功，并且可以安装该插件。

步骤 1. 使您的应用程序可访问

要在此实例上安装插件，您应该可以通过互联网访问。出于测试目的，最简单的方法是使用 ngrok。

然后您可以访问它，将您的实际网站URL放入环境变量 PLUGIN_URL。

确保您的插件可以通过 HTTPS 访问，这是必需的。

步骤 2. 配置您的JIRA / Confluence实例

使用 config/plugin.php 配置您的插件。大多数值都可以通过env变量覆盖。

步骤 3. 上传您的插件

最后，您需要上传插件。点击“上传插件”，并粘贴带有描述符路径的公共URL，例如 https://d1ea31ce.ngrok.io/atlassian-connect.json 或 https://yourplugindomain.com/atlassian-connect.json

步骤 4. 测试是否成功

安装成功后，在JIRA实例上，您可能会看到顶部的“您的插件”菜单项。您也可以通过直接链接访问插件通用页面 :product_base_url/plugins/servlet/ac/sample-plugin/hello-page

将 :product_base_url 替换为您JIRA或Cofluence实例的URL（例如 https://google-dev.atlassian.net）。

如果您看到页面正常工作，则表示应用程序配置正确且插件安装正确。

发布资源

您可以使用以下命令手动执行操作，而不是使用 plugin:install

要复制所有发布的内容，您应该使用以下命令

php artisan vendor:publish --provider="AtlassianConnectCore\ServiceProvider"

要复制特定发布，必须使用带有选项 --tag 的此命令。值可以是 public（复制资产）、views 和 config。

使用方法

默认路由

以下路由默认注册

• GET /atlassian-connect.json 描述符内容
• POST /installed 插件安装回调
• POST /uninstalled 插件卸载回调
• POST /enabled 插件启用回调
• POST /disabled 插件禁用回调
• GET /hello 样本页面以证明所有功能正常

您可以通过将配置值 plugin.loadRoutes 设置为 false 来禁用它们。

描述符

您可以使用 Descriptor 门面来自定义或从头开始创建自己的描述符内容。

例如，您可以通过向 app\Providers\AppServiceProvider 中的 boot 部分添加以下内容来自定义它

Descriptor::base() // base descriptor contents
    ->setScopes(['admin' , 'act_as_user'])
    ->withModules([
        'webhooks' => [[
            'event' => 'jira:issue_created',
            'url' => route('webhookHandlerRouteName')
        ]]
    ])
    ->set('version', $this->getLatestPluginVersion());

警告：如果您在 AppServiceProvider 中使用 route 辅助函数，您应该在您的 app.php 配置中在 AppServiceProvider 之上定义 RouteServiceProvider。

API 请求

在大多数 Atlassian 产品插件开发的情况下，您需要向实例执行请求。

对于这种情况，您可以使用 JWTClient。它使用 GuzzleHttp 作为 HTTP 客户端。

如果您想有自定义处理（中间件等），您可以将客户端实例传递给构造函数。

分页

如果您想向支持分页的端点发送请求，您应该使用 JWTClient::paginate 方法。在大多数情况下，您不需要将分页器实例传递给 JWTClient 构造函数，因为它将自动通过解析您的租户产品类型（JIRA 或 Confluence）来实例化，但您始终可以使用特定的分页器。

默认支持两种分页器

• JiraPaginator
• ConfluencePaginator

您始终可以扩展 Paginator 类并创建自己的。

示例

获取 Confluence 页面内容

use AtlassianConnectCore\Http\Clients\JWTClient;

/**
 * Retrieve a Confluence page content.
 *
 * @return array
 */
public function pageContent(int $id): array
{
    $client = new JWTClient($this->tenant); // or Auth::user() if you performing a request from the instance
    
    return $client->get('rest/api/content/' . $id, [
        'query' => [
            'expand' => 'body.storage'
        ]
    ]);
}

获取 JIRA 问题

use AtlassianConnectCore\Http\Clients\JWTClient;

/**
 * Retrieve an issue object.
 *
 * @return array
 */
public function viewIssue(string $key): array
{
    $client = new JWTClient($this->tenant);
    
    return $client->get('rest/api/2/issue/' . $key);
}

Webhooks

该插件提供了一个方便的方式来处理基于习惯的 Laravel 事件传入的 webhooks。

如果您不熟悉 Laravel 事件，请查看 Laravel 文档

定义 webhook 监听器有两种方式

1. 在 config/plugin.php 中定义监听器

'webhooks' => [
    'jira:issue_updated' => \App\Listeners\Webhooks\Issue\Created::class,
    ...
]

2. 使用 Webhook 门面定义监听器，例如

Webhook::listen('jira:issue_created', function(\AtlassianConnectCore\Models\Tenant $tenant, \Illuminate\Http\Request $request) {
    // ...
});

如你所见，您可以将事件监听器定义为闭包或 Laravel 语法中的字符串

Webhook::listen('jira:issue_created', \App\Listeners\Webhooks\Issue\Created::class);
Webhook::listen('jira:issue_created', 'App\Listeners\Webhooks\Issue\Created@handle');

您不需要在您的插件描述符中定义 webhooks，它们将自动描述。

示例监听器

<?php

namespace App\Listeners\Webhooks\Issue;

use Illuminate\Http\Request;
use AtlassianConnectCore\Models\Tenant;

class Created
{
    /**
     * Create the event listener.
     *
     * @return void
     */
    public function __construct()
    {
        //
    }

    /**
     * Handle the incoming webhook.
     *
     * @param \AtlassianConnectCore\Models\Tenant $tenant
     * @param \Illuminate\Http\Request $request
     *
     * @return void
     */
    public function handle(Tenant $tenant, Request $request)
    {
        // ...
    }
}

您的监听器也可以在构造函数上对任何依赖项进行类型提示。所有事件监听器都通过 Laravel 服务容器解决，因此依赖项将自动注入。

控制台命令

• plugin:install 是一个辅助命令，它使用假数据创建 "虚拟" 租户并发布包资源（配置、视图、资产）
• plugin:dummy 提供了一种交互式的方法来将租户设置为 "dummy"，无需手动编辑数据库

测试

在包文件夹中运行以下命令

vendor/bin/phpunit

安全

如果您发现任何与安全相关的问题，请通过电子邮件 brezzhnev@gmail.com 联系，而不是使用问题跟踪器。

鸣谢

• brezzhnev
• 所有贡献者

许可

MIT 许可协议 (MIT)。请参阅 许可文件 获取更多信息。