README

欢迎使用 Laravel Github to Notion Webhooks 包的文档！此简单包让您能够轻松地将 GitHub 事件（如拉取请求和问题）同步到 Notion。通过处理配置和同步过程，它可以让您专注于工作。让我们深入探讨并开始吧！

该包利用另一个名为 Laravel-Notion-Integration 的包，允许您无缝地与 Notion API 交互。

安装

要开始使用此包，请通过 composer 安装

composer require pi-space/laravel-github-to-notion-webhooks

安装后，您需要发布配置文件以自定义包设置

php artisan vendor:publish --tag="laravel-github-to-notion-webhooks-config"

发布的配置文件如下所示

return [
    'github' => [
        'secret' => env('GITHUB_WEBHOOK_SECRET'),
        'events' => [
            'issue' => true,
            'pull_request' => true,
        ],
    ],
    'notion' => [
        'databases' => [
            'issues' => 'cc66f47f03cb4b62a774f6d5f34463ce',
            'pull-requests' => 'b99a0a1287d142bbbd7bec87fe1e6406',
            'users' => '430cedc2495348df926ca520e1255182',
        ],
    ]
];

发布的配置文件包含两个主要部分：github 和 notion。

GitHub 配置

github 部分指定了 GitHub webhook 的配置，包括您想要监听的事件以及用于验证 webhook 请求到您的 Laravel 应用的密钥。要使用该包，您需要在 .env 文件中添加密钥。有关 GitHub webhooks 和如何设置的更多信息，请参阅 GitHub 文档此处。

在您的 GitHub 仓库设置中，您需要做两件事

将您的 Laravel 应用的 URL 作为 webhook URL 添加，这将成为您应用的基础 URL + /github/webhooks。例如：https://example.com/github/webhooks。
指定您希望 GitHub 发送到您应用的事件。完成此操作后，将它们添加到配置文件中的 events 键，如果您想禁用任何事件，可以将它的值设置为 false。

Notion 配置

notion 部分指定了您想要存储同步数据的 Notion 数据库 ID。您可以手动创建 Notion 数据库或使用 artisan 命令来为您生成数据库并返回 ID。如果您选择后者，请按照以下步骤操作

请注意，这将生成一个具有预定义属性名称和类型的特定数据库。如果您想自定义属性，请参阅#自定义部分。请注意，Notion 中的用户数据库是必需的，因为它将被用于识别 GitHub 用户名并将其映射到 Notion 用户。请确保手动填写表格，写入每个 GitHub 用户名，然后在“人员”属性中提及相应的 Notion 用户。

调用 artisan 命令以在 Notion 中创建数据库并获取 ID

php artisan notion:create-databases {parentPageId}

请注意，parentPageId 是您想要创建数据库的页面的 ID。您可以通过转到页面，点击“共享”，然后复制链接来找到此 ID。ID 是链接中页面名称之后的部分。

例如，如果链接是 https://www.notion.so/My-Page-Name-430cedc2495348df926ca520e1255182，则 ID 为 430cedc2495348df926ca520e1255182。

命令将返回类似以下内容

Issues database created successfully with id: cc66f47f03cb4b62a774f6d5f34463ce
Pull Requests database created successfully with id: b99a0a1287d142bbbd7bec87fe1e6406
Users database created successfully with id: 430cedc2495348df926ca520e1255182

将 ID 粘贴到配置文件中的 notion.databases 部分中，如上一个示例所示。
将 Notion API 密钥和数据库 ID 添加到 .env 文件中，如下所示，有关 Notion API 密钥的更多信息，请参阅Notion API 文档

NOTION_TOKEN=secret_{your_token}

使用方法

这就完成了！你已经设置好了！包会处理剩下的工作。现在你可以前往你的GitHub仓库，创建一个issue或pull request，你会看到数据自动同步到Notion。如果你想更改属性名称或类型，你可以继续阅读文档。另外，如果你想监听当前包不支持的其他事件，请参考贡献部分并发送一个pull request。

自定义

如果你想要为Notion中的数据库自定义属性名称或类型，本节为你提供了解决方案。以下是如何进行必要的调整的步骤

映射到Notion数据库

该包根据一组转换器将GitHub中的数据映射到Notion。例如，issue转换器负责将GitHub中的issue数据映射到Notion的issue数据库中，pull request转换器和用户转换器也是如此。你可以创建自己的转换器，并根据需要映射数据。但是请注意以下几点

转换器必须实现一个特定的接口。例如，对于IssueTransformer，你必须实现IssueTransformerInterface，然后像这样在你的服务提供者中将自己的实现绑定到接口中

$this->app->bind(IssueTransformerInterface::class, IssueTransformer::class);

请注意，数据库需要有一个名为ID的文本列。这个唯一的ID用于识别数据库中的记录，并在记录已存在时更新它。因此，请确保将此列添加到您的数据库中。
转换器的键需要与基础Transformer相同；它们实际上是实体的属性名称。

通过这些更改，你就可以根据特定需求自定义转换器。有关如何将属性映射到你的Notion数据库的更多详细信息，你可以参考Laravel-Notion-Integration文档。

贡献

该包目前仅支持issues和pull requests。如果你想添加对其他事件的支撑，你非常欢迎通过发送一个pull request来实现。为了帮助你了解如何添加对其他事件的支撑，让我们了解一下包的内部结构

包内部结构

Webhook控制器

Webhook控制器负责接收来自GitHub的webhook请求。它首先运行两个中间件：VerifyWebhookSignature中间件，用于验证请求签名以确保请求确实来自GitHub，以及VerifyWebhookEvent中间件，用于验证事件类型。然后将事件类型与负载合并为Enum "GithubEventTypeEnum"，并传递给GithubRequest类。

GithubRequest类

GithubRequest类负责解析负载并以结构化方式返回数据，例如创建相关的实体及其相关用户。

GitHub实体

该包有三个实体：Issue、PullRequest和User。每个实体都有自己的转换器，负责将GitHub中的数据映射到Notion数据库。实体还会设置Notion数据库ID，根据请求数据设置类属性，然后调用转换器将数据映射到Notion数据库。

GithubWebhookHandler

处理程序接受GithubRequest，然后调用适当的行为，无论是创建数据库中的页面、更新它还是删除它。

实现新事件

如果你想添加对新事件的支持

将事件类型添加到GithubEventTypeEnum。
为事件创建一个新实体。例如，如果你想添加对"push"事件的支持，你将创建一个名为GithubPush的新实体，它扩展了GithubEntity类，然后实现抽象方法。
为新实体创建一个转换器类和接口。在mapToNotion方法中使用它，并记得在包服务提供者中将接口绑定到实现。
创建一个测试，使用JSON有效载荷进行测试，并确保通过。
提交PR！

测试

您可以使用以下命令运行该包的测试：

composer test

更新日志

有关该包变更的详细历史记录，请参阅更新日志。

安全漏洞

如果您发现任何安全漏洞，请遵循我们的安全策略来报告它们。

鸣谢

许可证

Laravel Github to Notion Webhooks包是开源软件，遵循MIT许可证。

pi-space / laravel-github-to-notion-webhooks

维护者

详细信息