README

Laravel 包，用于与 Jira Webhooks 交互。

安装

通过 Composer 安装此包

composer require stichoza/jira-webhooks-laravel

此包使用 Laravel 的包自动发现功能，因此您无需手动添加服务提供者。

Laravel 无自动发现

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

Stichoza\JiraWebhooksLaravel\JiraWebhooksLaravelServiceProvider::class,

如果您想使用外观路由，请将以下内容添加到 config/app.php 文件中的 aliases 中

'JiraWebhooks' => Stichoza\JiraWebhooksLaravel\JiraWebhooks::class,

导出配置文件

(可选) 如果您想自定义包发送的事件，请使用发布命令将包配置复制到您的本地配置

php artisan vendor:publish --provider="Stichoza\JiraWebhooksLaravel\JiraWebhooksLaravelServiceProvider" --tag=config

添加 Webhook 路由

您可以使用 JiraWebhooks 类将 webhook 路由添加到您的路由文件中

JiraWebhooks::route();

这将为 URI jira-webhook 创建一个 POST 路由。您也可以通过传递参数来自定义路由的 URI。此方法返回 Illuminate\Routing\Route 对象，因此您可以像使用常规路由一样使用所有其他方法。

JiraWebhooks::route('jira/my_webhook')->middleware(SomeMiddleware::class);

CSRF 保护

如果您将路由添加到您的 web 路由中，请确保您已禁用 webhook 路由的 CSRF 中间件。为此，请将 URI 添加到 VerifyCsrfToken 中间件的 $except 属性中。

protected $except = [
    // ...
    'jira-webhook', // or the custom URI you passed to `JiraWebhooks::route()`
];

使用

默认情况下，该包将为任何传入的 webhook 发送 Stichoza\JiraWebhooksLaravel\Events\JiraWebhookReceived 事件，以及根据接收到的 webhook 的 webhookEvent 发送特定的事件。

使用事件

以下是 Jira webhookEvent 事件名称和此包发送的相应事件的表格

注意 默认事件位于 Stichoza\JiraWebhooksLaravel\Events 命名空间中。

定义自定义事件

您可以通过在 config/jira-webhooks.php 文件中添加不同的事件来扩展或自定义事件映射。这些是您可以通过 php artisan make:event 命令创建的常规事件。

'events' => [
    // '*' => \Stichoza\JiraWebhooksLaravel\Events\JiraWebhookReceived::class,
    'jira:issue_created' => \App\Events\JiraIssueCreated::class,
    'jira:issue_updated' => \App\Events\JiraIssueUpdated::class,
    'comment_created' => \App\Events\JiraCommentCreated::class,
    'issuelink_*' => \App\Events\JiraIssueLinkCreatedOrDeleted::class,
    // ...
],

所有事件都将接收到构造函数中的 Stichoza\JiraWebhooksData\Models\JiraWebhookData 对象。

键将与 Jira 的 webhook 事件名称（webhookEvent 属性）进行匹配，使用 Str::is() 方法，因此您可以在名称中使用通配符。您可以在这里找到 Jira webhook 事件名称的完整列表。

注意 将触发与模式匹配的所有事件，而不仅仅是第一个。

处理事件

您应该在 config/jira-webhooks.php 文件中配置的事件中定义监听器。您可以使用 Laravel 的 php artisan make:listener 命令创建监听器。

所有事件都将有一个类型为 Stichoza\JiraWebhooksData\Models\JiraWebhookData 的 webhook 属性。此对象包含 webhook 请求的所有数据。有关这些数据结构的更多信息，请参阅 stichoza/jira-webhooks-data 包的说明。

示例

<?php

namespace App\Listeners;

use App\Events\JiraCommentCreated;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\InteractsWithQueue;

class JiraCommentCreatedListener implements ShouldQueue
{
    use InteractsWithQueue;

    public function handle(JiraCommentCreated $event): void
    {
        $title = 'New comment by ' . $event->webhook->comment->author->displayName
            . ' on issue ' . $event->webhook->issue->key;

        $message = $event->webhook->comment->author->displayName
            . ' said: ' . $event->webhook->comment->body;

        // Do something else
    }
}

建议

建议将监听器排队。此包返回 200 OK 响应给 Jira，因此如果响应需要太长时间，Jira 将假设 webhook 交付失败。