mccaulay/discord-notification-channel

Discord Notification Channel for laravel.

v1.0.0 2019-09-11 19:27 UTC

README

Total Downloads Latest Stable Version License

Documentation

Prerequisites

Before you can send notifications via Discord, you must install the notification channel via Composer:

composer require mccaulay/discord-notification-channel

You will also need to configure a "Webhook" integration for your Discord channel. This integration will provide you with a URL you may use when routing Discord notifications.

Formatting Discord Notifications

If a notification supports being sent as a Discord message, you should define a toDiscord method on the notification class. This method will receive a $notifiable entity and should return a Illuminate\Notifications\Messages\DiscordMessage instance. Discord messages may contain text content as well as an "embed" that formats additional text or an array of fields. Let's take a look at a basic toDiscord example:

/**
 * Get the Discord representation of the notification.
 *
 * @param  mixed  $notifiable
 * @return DiscordMessage
 */
public function toDiscord($notifiable)
{
    return (new DiscordMessage)
                ->content('One of your invoices has been paid!');
}

In this example we are just sending a single line of text to Discord, which will create a message that looks like the following:

basic-discord-notification.png

Customizing The Sender & Recipient

You may use the from method to customize the sender. The from method accepts a username:

/**
 * Get the Discord representation of the notification.
 *
 * @param  mixed  $notifiable
 * @return DiscordMessage
 */
public function toDiscord($notifiable)
{
    return (new DiscordMessage)
                ->from('John Doe')
                ->content('This will be sent from John Doe');
}

You may also use an image as your logo instead of the default image:

/**
 * Get the Discord representation of the notification.
 *
 * @param  mixed  $notifiable
 * @return DiscordMessage
 */
public function toDiscord($notifiable)
{
    return (new DiscordMessage)
                ->from('Laravel')
                ->image('https://laravel.com/favicon.png')
                ->content('This will display the Laravel logo next to the message');
}

Discord Embeds

You may also add "embeds" to Discord messages. Embeds provide richer formatting options than simple text messages. In this example, we will send an error notification about an exception that occurred in an application, including a link to view more details about the exception:

/**
 * Get the Discord representation of the notification.
 *
 * @param  mixed  $notifiable
 * @return DiscordMessage
 */
public function toDiscord($notifiable)
{
    $url = url('/exceptions/'.$this->exception->id);

    return (new DiscordMessage)
                ->error()
                ->content('Whoops! Something went wrong.')
                ->embed(function ($embed) use ($url) {
                    $embed->title('Exception: File Not Found', $url)
                               ->content('File [background.jpg] was not found.');
                });
}

The example above will generate a Discord message that looks like the following:

basic-discord-embed.png

Embeds also allow you to specify an array of data that should be presented to the user. The given data will be presented in a table-style format for easy reading:

/**
 * Get the Discord representation of the notification.
 *
 * @param  mixed  $notifiable
 * @return DiscordMessage
 */
public function toDiscord($notifiable)
{
    $url = url('/invoices/'.$this->invoice->id);

    return (new DiscordMessage)
                ->success()
                ->content('One of your invoices has been paid!')
                ->embed(function ($embed) use ($url) {
                    $embed->title('Invoice 1322', $url)
                               ->fields([
                                    'Title' => 'Server Expenses',
                                    'Amount' => '$1,234',
                                    'Via' => 'American Express',
                                    'Was Overdue' => ':-1:',
                                ]);
                });
}

The example above will create a Discord message that looks like the following:

discord-fields-embed.png

Routing Discord Notifications

To route Discord notifications to the proper location, define a routeNotificationForDiscord method on your notifiable entity. This should return the webhook URL to which the notification should be delivered. Webhook URLs may be generated through discord on the channel settings:

<?php

namespace App;

use Illuminate\Notifications\Notifiable;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    use Notifiable;

    /**
     * Route notifications for the Discord channel.
     *
     * @param  \Illuminate\Notifications\Notification  $notification
     * @return string
     */
    public function routeNotificationForDiscord($notification)
    {
        return 'https://discordapp.com/api/webhooks/...';
    }
}

License

Laravel Discord Notification Channel is open-sourced software licensed under the MIT license.