> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Laravel Notification for Discord(Webhook)

> 使用 Discord Webhook 從 Laravel 輕鬆傳送通知的套件。無需 Bot、無需 WebSocket,只要設定 Webhook URL 即可使用。

## 概觀

[revolution/laravel-notification-discord-webhook](https://github.com/invokable/laravel-notification-discord-webhook) 是使用 Discord Webhook,從 Laravel Notifications 向 Discord 傳送通知的套件。

Discord 正式的 Bot API 需要維持 WebSocket 連線,設定較為複雜。而 Webhook 只要取得 URL 即可傳送通知。若只是想將應用程式事件通知到團隊的 Discord 頻道,Webhook 是最佳選擇。

<Info>
  本套件需要 PHP 8.3 以上、Laravel 12.0 以上。
</Info>

## 安裝

```shell theme={null}
composer require revolution/laravel-notification-discord-webhook
```

## 設定

### 取得 Discord 的 Webhook URL

可於 Discord 伺服器的 **設定 → 整合 → Webhook** 建立 Webhook URL。詳細請參閱 [Discord 官方指南](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks)。

### config/services.php

```php theme={null}
'discord' => [
    'webhook' => env('DISCORD_WEBHOOK'),
],
```

### .env

```dotenv theme={null}
DISCORD_WEBHOOK=https://discord.com/api/webhooks/...
```

## 基本用法

### 建立 Notification 類別

實作 `toDiscordWebhook()` 方法,並於 `via()` 傳回 `DiscordChannel::class`。

```php theme={null}
<?php

namespace App\Notifications;

use Illuminate\Bus\Queueable;
use Illuminate\Notifications\Notification;
use Illuminate\Contracts\Queue\ShouldQueue;
use Revolution\Laravel\Notification\DiscordWebhook\DiscordChannel;
use Revolution\Laravel\Notification\DiscordWebhook\DiscordMessage;

class DiscordNotification extends Notification implements ShouldQueue
{
    use Queueable;

    public function __construct(protected string $content)
    {
        //
    }

    public function via($notifiable): array
    {
        return [DiscordChannel::class];
    }

    public function toDiscordWebhook(object $notifiable): DiscordMessage
    {
        return DiscordMessage::create(content: $this->content);
    }
}
```

## 傳送模式

### On-Demand 通知

若不綁定特定 User 模型即傳送通知,可使用 `Notification::route()`。

```php theme={null}
use Illuminate\Support\Facades\Notification;

Notification::route('discord-webhook', config('services.discord.webhook'))
            ->notify(new DiscordNotification('部署完成。'));
```

### 從 User 模型傳送通知

若要為每個 User 使用不同的 Webhook URL,可定義 `routeNotificationForDiscordWebhook()`。

```php theme={null}
use Illuminate\Notifications\Notifiable;

class User extends Authenticatable
{
    use Notifiable;

    public function routeNotificationForDiscordWebhook($notification): string
    {
        return $this->discord_webhook;
    }
}
```

```php theme={null}
$user->notify(new DiscordNotification('測試通知'));
```

## 訊息類型

### 文字訊息

最簡單的傳送方式。

```php theme={null}
public function toDiscordWebhook(object $notifiable): DiscordMessage
{
    return DiscordMessage::create(content: $this->content);
}
```

### Embed 訊息

使用 `DiscordEmbed` 可呈現包含標題與 URL 的豐富顯示。

```php theme={null}
use Revolution\Laravel\Notification\DiscordWebhook\DiscordMessage;
use Revolution\Laravel\Notification\DiscordWebhook\DiscordEmbed;

public function toDiscordWebhook(object $notifiable): DiscordMessage
{
    return DiscordMessage::create()
                          ->embed(
                              DiscordEmbed::make(
                                  title: 'INFO',
                                  description: $this->content,
                                  url: route('home'),
                              )
                          );
}
```

### 檔案附件

使用 `DiscordAttachment` 可以附加檔案傳送。`content`(檔案內容)與 `filename` 為必填。

```php theme={null}
use Revolution\Laravel\Notification\DiscordWebhook\DiscordMessage;
use Revolution\Laravel\Notification\DiscordWebhook\DiscordAttachment;
use Illuminate\Support\Facades\Storage;

public function toDiscordWebhook(object $notifiable): DiscordMessage
{
    return DiscordMessage::create()
        ->file(
            DiscordAttachment::make(
                content: Storage::get('test.png'),
                filename: 'test.png',
                description: 'test',
                filetype: 'image/png'
            )
        );
}
```

### 於 Embed 中參照檔案

可於 Embed 的 `image` 或 `thumbnail` 以 `attachment://檔名` 參照附件檔案。

```php theme={null}
use Revolution\Laravel\Notification\DiscordWebhook\DiscordMessage;
use Revolution\Laravel\Notification\DiscordWebhook\DiscordAttachment;
use Revolution\Laravel\Notification\DiscordWebhook\DiscordEmbed;
use Illuminate\Support\Facades\Storage;

public function toDiscordWebhook(object $notifiable): DiscordMessage
{
    return DiscordMessage::create()
                          ->embed(
                              DiscordEmbed::make(
                                  title: 'test',
                                  description: $this->content,
                                  image: 'attachment://test.jpg',
                                  thumbnail: 'attachment://test2.jpg',
                              )
                          )
                          ->file(DiscordAttachment::make(
                              content: Storage::get('test.jpg'),
                              filename: 'test.jpg',
                              description: 'test',
                              filetype: 'image/jpg'
                          ))
                          ->file(new DiscordAttachment(
                              content: Storage::get('test2.jpg'),
                              filename: 'test2.jpg',
                              description: 'test2',
                              filetype: 'image/jpg'
                          ));
}
```

### 傳送任意 Payload

使用 `->with()` 可直接指定 Discord Webhook 的任意參數。

```php theme={null}
public function toDiscordWebhook(object $notifiable): DiscordMessage
{
    return DiscordMessage::create()
                          ->with([
                              'content' => $this->content,
                              'embeds' => [[]],
                          ]);
}
```

<Tip>
  可透過 `->with()` 指定的參數詳情請參閱 [Discord 官方 API 文件](https://discord.com/developers/docs/resources/webhook#execute-webhook)。
</Tip>

## 總結

Discord Bot 雖然強大,但若只是要傳送通知,Webhook 簡潔許多。使用本套件可以無縫整合 Laravel 的通知系統,快速將應用程式事件通知至團隊的 Discord 頻道。

<Info>
  最新資訊請參閱 [GitHub 儲存庫](https://github.com/invokable/laravel-notification-discord-webhook)。
</Info>


## Related topics

- [我的包](/zh-CN/packages/index.md)
- [教學 - Laravel Console Starter](/zh-TW/packages/laravel-console-starter/tutorial.md)
- [Envoy](/zh-TW/envoy.md)
- [Socialite for Discord](/zh-TW/packages/socialite-discord.md)
- [LINE SDK for Laravel](/zh-TW/packages/laravel-line-sdk/index.md)