README

Google Chat - Laravel 通知渠道

此包使得使用 Google Chat (原名：Hangouts Chat) 在 Laravel 9.x 中发送通知变得简单。

class InvoicePaidNotification extends Notification
{
    // Create a super simple message
    public function toGoogleChat($notifiable)
    {
        return GoogleChatMessage::create('An invoice was paid!');
    }

    // ...Or you can use some simple formatting
    public function toGoogleChat($notifiable)
    {
        return GoogleChatMessage::create()
            ->text('Someone just paid an invoice... ')
            ->bold('Woo-hoo!')
            ->line('Looking for ')
            ->link(route('invoices'), 'the details?')
            ->to('sales_team'); // ... and route it to specific rooms
    }

    // ...You can even make a fancy card!
    public function toGoogleChat($notifiable)
    {
        return GoogleChatMessage::create()
            ->text('Invoice Paid! Here\'s the details:')
            ->card(
                Card::create(
                    Section::create(
                        KeyValue::create('Amount', '$520.99', '#10004756')
                            ->onClick(route('invoices'))
                            ->button(TextButton::create(route('invoices'), 'View'))
                    )
                )
            )
    }
}

对于 Laravel 8.x，请使用此包的 1.x 版本。

内容

安装
- 生成 Webhook
配置和使用您的应用程序中的 Webhook
使用方法
- 简单消息
- 卡片消息
API 概述
更新日志
测试
安全
贡献
鸣谢
许可

安装

通过 Composer 可以轻松安装 Google Chat 通知渠道。

$ composer require laravel-notification-channels/google-chat

生成 Webhook

此包利用了 Google Chat 方便的 'Webhook' 功能，允许快速轻松地设置。

您可以在 Google 的文档中了解如何创建房间并生成新的 Webhook。

在整个 Google 的文档中，术语 'space' 用来泛指 Google Chat 中的对话，无论是同事之间的单人聊天，还是多人之间的 'room'。

虽然此包只能将消息发送到 'rooms'，但我们仍然在本包的文档和 Google 的文档中统一称为 'space'。

配置和使用您的应用程序中的 Webhook

首先，我们将 Google Chat 通知渠道使用的配置文件发布到您的应用程序中，这样我们就可以开始配置我们的 Webhook 了。

$ php artisan vendor:publish --tag google-chat-config

默认房间

如果我们只想将消息发布到单个房间/webhook，我们可以简单地配置 space 键，它定义了通过 Google Chat 渠道发送的默认对话通知将被发布到。

// config/google-chat.php

return [
    'space' => 'https://chat.googleapis.com/room-webhook-for-all-notifications?key=xxxxx'
]

未指定其他房间发送的通知现在将被发送到这个默认空间。

注意！ 如果您的应用程序通过 Google Chat 发送敏感通知，我们建议您将 space 键配置为 NULL，这样通知必须明确地指向一个端点。

备用房间（推荐）

您还可以在 spaces (复数) 键下定义备用 Webhook，并在应用程序中更容易地引用这些 Webhook。

// config/google-chat.php

return [
    'spaces' => [
        'sales_team' => 'https://chat.googleapis.com/sales-team-room?key=xxxxx',
        'dev_team' => 'https://chat.googleapis.com/dev-team-room?key=xxxxx',
        'executive' => 'https://chat.googleapis.com/executives?key=xxxxx',
    ]
]

您现在可以通过在任何可以路由通知的地方使用相关键来将通知定向到配置好的这些房间之一。

Notification::route('googleChat', 'sales_team')->...

// Or

GoogleChatMessage::create()->to('dev_team')->...

// Or, even in your notifiable class:
public function routeNotificationForGoogleChat()
{
    return 'executive';
}

显式 Webhook 路由

如果需要，您可以将通知路由到上面列出的所有相同位置的显式 Webhook。然而，这不是首选方法，因为它在您需要更改 Webhook 时会提供较少的灵活性。

Notification::route('googleChat', 'https://chat.googleapis.com/xxxxx')->...

// Or

GoogleChatMessage::create()->to('https://chat.googleapis.com/xxxxx')->...

// Or, even in your notifiable class:
public function routeNotificationForGoogleChat()
{
    return 'https://chat.googleapis.com/xxxxx';
}

使用方法

为了通过 Google Chat 渠道发送通知，您需要在通知的 via() 方法中指定该渠道

use NotificationChannels\GoogleChat\GoogleChatChannel;

// ...

public function via($notifiable)
{
    return [
        GoogleChatChannel::class
    ]
}

如果您还没有，请确保您理解通知类是如何构建的。

Google Chat 消息有两种格式：简单消息和卡片消息。此包允许您构建这两种格式。

简单消息

使用NotificationChannels\GoogleChat\GoogleChatMessage实例直接创建简单消息非常简单，并像这样在您的通知类中返回：

use NotificationChannels\GoogleChat\GoogleChatMessage;

public function toGoogleChat($notifiable)
{
    return GoogleChatMessage::create('Hello world!');
}

简单消息也可以包含基本的格式化。

use NotificationChannels\GoogleChat\GoogleChatMessage;

public function toGoogleChat($notifiable)
{
    return GoogleChatMessage::create()
        ->bold('Heads Up!')
        ->line('An error was encountered whilst communicating with an external service:')
        ->monospaceBlock($this->errorMessage)
        ->italic('Want to know more? ')
        ->link('https://status.example.com/logs', 'Check Out the Logs.');
}

卡片消息

Google Chat卡片是更复杂的UI元素，可以向接收者展示组织好的信息。卡片添加到GoogleChatMessage实例中，可以与简单消息一起使用。

此包中卡片的结构非常接近发送到webhook端点的实际数据格式。因此，查看卡片的结构是值得的。

use NotificationChannels\GoogleChat\GoogleChatMessage;
use NotificationChannels\GoogleChat\Card;
use NotificationChannels\GoogleChat\Section;
use NotificationChannels\GoogleChat\Widgets\KeyValue;
use NotificationChannels\GoogleChat\Enums\Icon;
use NotificationChannels\GoogleChat\Enums\ImageStyle;

public function toGoogleChat($notifiable)
{
    return GoogleChatMessage::create()
        ->text('An invoice was just paid... ')
        ->bold('Woo-hoo!')
        ->card(
            Card::create()
                ->header(
                    'Invoice Paid',
                    '#1004756',
                    'https://cdn.example.com/avatars/xxx.png',
                    ImageStyle::CIRCULAR
                )
                ->section(
                    Section::create(
                        KeyValue::create(
                            'Payment Received',
                            '$20.14',
                            'Paid by Josephine Smith'
                        )
                        ->icon(Icon::DOLLAR)
                        ->onClick(route('invoice.show'))
                    )
                )
        )
}

视觉学习者？我们也一样。以下是卡片结构的视觉概述。

cards
|
|---card
|   |
|   |---header (complex)
|   |   ...
|   |
|   |---sections
|   |   |
|   |   |---section
|   |   |   |
|   |   |   |---header (simple)
|   |   |   |   ...
|   |   |   |
|   |   |   |---widgets
|   |   |   |   |
|   |   |   |   |---widget
|   |   |   |   |   ...
|   |   |   |   |
|   |   |   |   |---widget
|   |   |   |   |   ...
|   |   |
|   |   |---section
|   |   |   ...
|
|---card
|   ...

API 概述

Google Chat 消息

命名空间：NotificationChannels\GoogleChat\GoogleChatMessage

GoogleChatMessage类包含了将被发送到Google Chat聊天室的全部消息。

static create(?string $text) 创建并返回一个新的GoogleChatMessage实例，可选地使用提供的简单文本预先配置。
to(string $space) 指定此通知将发送到的webhook或空间密钥。这优先于默认空间以及通知器的routeNotificationForGoogleChat()方法返回的任何值。
text(string $message) 将$message追加到简单消息内容中。
line(string $message) 在新行上追加$message。
bold(string $message) 追加粗体文本。
italic(string $message) 追加斜体文本。
strikethrough(string $message) 追加删除线文本。
strike(string $message) strikethrough()的别名。
monospace(string $message) 追加等宽文本。
mono(string $message) monospace()的别名。
monospaceBlock(string $message) 追加一个等宽文本块。
link(string $link, ?string $displayText) 追加一个文本链接，可选地带有自定义显示文本。
mention(string $userId) 追加一个针对特定用户ID的提及文本。
mentionAll(?string $prependText, ?string $appendText) 追加一个提及所有人文本，可选地在块前后添加文本。
card(Card|Card[] $card) 向消息添加一个或多个复杂的卡片UI。

卡片布局

布局分为两个概念：卡片和部分。卡片可以看作容器，而部分可以看作卡片内部的行。卡片可以有一个复杂的总标题，而每个部分可以包含一个简单的基于文本的标题。

您可以向卡片添加多个部分，以分组相关信息。

卡片

命名空间：NotificationChannels\GoogleChat\Card

Card类代表将发送到消息中的卡片UI的顶层布局定义。卡片定义一个或多个部分，可以可选地定义标题信息。

static create(Section|Section[]|null $section) 创建并返回一个新的Card实例，可选地使用提供的部分或部分数组预先配置。
header(string $title, ?string $subtitle, ?string $imageUrl, ?string $imageStyle) 可选 - 配置卡片的标题UI。注意，$imageStyle是NotificationChannels\GoogleChat\Enums\ImageStyle中定义的常量之一。
section(Section|Section[] $section) 向卡片添加一个或多个部分。

部分

命名空间：NotificationChannels\GoogleChat\Section

Section类定义了卡片的中级布局定义。从UI角度来看，它将相关的小部件分组。

static create(AbstractWidget|AbstractWidget[]|null $widgets) 创建并返回一个新的Section实例，可选地使用提供的小部件或小部件数组预先配置。
header(string $text) 可选地定义在部分顶部显示的简单标题。
widget(AbstractWidget|AbstractWidgets[] $widget) 向部分添加一个或多个小部件。

小部件

小部件是显示在单个卡片中的有意义的UI元素。有不同类型的小部件，以便更合适地显示信息给用户。

小部件被添加到某个部分中，一个部分可以包含多个不同类型的小部件。

文本段落

命名空间：NotificationChannels\GoogleChat\Widgets\TextParagraph

TextParagraph 小部件定义了富文本。这个小部件可以定义比简单消息允许的更复杂的文本格式。

static create(?string $message) 实例化并返回一个新的 TextParagraph 实例，可选地使用提供的文本预先配置它。
text(string $message) 将 $message 添加到小部件内容中。
bold(string $message) 追加粗体文本。
italic(string $message) 追加斜体文本。
underline(string $message) 添加下划线文本。
strikethrough(string $message) 添加删除线文本。
strike(string $message) strikethrough()的别名。
color(string $message, string $hex) 根据指定的 $hex 颜色添加彩色文本。
link(string $link, ?string $displayText) 添加文本链接，可选地带有提供的显示文本。
break() 添加换行。

键值对

命名空间：NotificationChannels\GoogleChat\Widgets\KeyValue

KeyValue 小部件定义了一个类似表格的元素，可以分割信息并提供外部点击。

static create(?string $topLabel, ?string $content, ?string $bottomLabel) 实例化并返回一个新的 KeyValue 实例，可选地使用顶部标签、内容和底部标签预先配置它。
topLabel(string $message) 定义顶部标签文本。
content(string $content) 定义小部件的主要文本内容。
bottomLabel(string $message) 定义底部标签文本。
setContentMultiline(bool $value) 确定主要内容是否应换行显示。Google默认此值为 false。
onClick(string $url) 定义一个点击通过URL，可以通过点击小部件本身来激活。注意，这与按钮的定义不同，按钮可以可选地添加到小部件中。
icon(string $icon) 定义与文本内容一起显示的符号图标；在 NotificationChannels\GoogleChat\Enums\Icon 中定义的常量之一。
button(AbstractButton $button) 可选地定义与文本内容一起显示的按钮。

图像

命名空间：NotificationChannels\GoogleChat\Widgets\Image

Image 小部件定义了一个要显示在卡片中的简单图像。可选地，可以配置一个点击通过URL，当用户点击/轻触图像时将激活。

static create(?string $imageUrl, ?string $onClickUrl) 实例化并返回一个新的 Image 实例，可选地使用图像URL和点击通过URL预先配置它。
imageUrl(string $url) 定义图像URL，可以从该URL获取图像。
onClick(string $url) 定义用户点击/轻触图像时将被带到的URL。

按钮

命名空间：NotificationChannels\GoogleChat\Widgets\Buttons

Buttons 小部件作为一个或多个按钮的容器，水平排列。该小部件接受 NotificationChannels\GoogleChat\Components\Button\AbstractButton 的实例，可以接受不同类型的按钮。

static create(AbstractButton|AbstractButton[]|null $buttons) 实例化并返回一个新的 Buttons 实例，可选地使用提供的按钮预先配置它。
button(AbstractButton|AbstractButton[] $button) 添加一个或多个按钮。

组件

组件是嵌套在组件内的结构。为了简单起见，Google Chat通知渠道仅支持按钮组件。

文本按钮和图像按钮都可以嵌套在 Buttons 小部件内，以及 KeyValue 和 ImageWidget 的按钮属性中。

文本按钮

命名空间：NotificationChannels\GoogleChat\Components\Button\TextButton

TextButton 定义了一个简单的文本按钮，并且可以在接受 AbstractButton 的任何地方接受。

static create(?string $url, ?string $displayText) 实例化并返回一个新的 TextButton 实例，可选地使用提供的URL和显示文本预先配置它。
url(string $url) 定义按钮的目标端点
text(string $text) 定义按钮的显示文本

图像按钮

命名空间：NotificationChannels\GoogleChat\Components\Button\ImageButton

ImageButton 定义可点击的图标或图像，可以在接受 AbstractButton 的任何位置使用。图标可以是默认图标（在 NotificationChannels\GoogleChat\Enums\Icon 中定义的常量之一）或外部图像 URL。

static create(?string $url, ?string $icon) 实例化并返回一个新的 ImageButton 实例，可选地使用提供的 URL 和图标预先配置它
url(string $url) 定义按钮的目标端点
icon(string $icon) 定义按钮要显示的图标或图像。

更新日志

有关最近更改的更多信息，请参阅变更日志。

测试

$ composer test

测试套件还包括一个端到端测试。为了使此测试通过，应设置环境变量 GOOGLE_CHAT_TEST_SPACE，其中包含测试房间的 webhook。

或者，您可以在本地开发期间使用 PHPUnit 排除此测试

$ ./vendor/bin/phpunit --exclude-group external

安全

如果您发现任何安全相关的问题，请通过[email protected] 发送电子邮件，而不是使用问题跟踪器。

laravel-notification-channels / google-chat

维护者

详细信息