[3.0] Support BlockKit / WebAPI-based bot notifications

[claudiodekker]

WARNING: THIS PR IS BREAKING.

It introduces a whole new way of interacting with Slack, meaning this is a breaking change. However, it is worth it.

Put simple, this PR "upgrades" the Slack Notification Channel package from simple Webhook-based calls, to WebAPI based calls. This opens up a whole range of new options:

• It allows for using BlockKit, Slack's rich message builder.
• It allows for interactivity. For example, you could add a Button to your message that when clicked, shows a confirmation dialog, and when that's confirmed, triggers Slack into calling a webhook you've configured in your Slack App.

While this WebAPI works based on OAuth tokens, the tokens themselves by default do not have a refresh token, and therefore do not expire either. This essentially makes it technically work the same as a webhook, with the only distinction being that instead of an Unique URL being used, an Authentication Bearer token is used.

Installation

• First, you'll want to create a new Slack app (or use an existing one): https://api.slack.com/apps?new_app=1 Example: https://user-images.githubusercontent.com/1752195/228922553-5301bcfd-4b3d-4407-8ad2-aa28bf82c662.png

• Next, click on Permissions, and scroll down to "Scopes". There, add the following scopes: Example: ![CleanShot 2023-03-30 at 19 54 40]()

• Finally, scroll back up and click "Install to Workspace": Example: https://user-images.githubusercontent.com/1752195/228922887-7091b1c5-24de-4667-815e-4c8036137b02.png

• After approving the app to your Slack Workspace, you'll see a "Bot User OAuth Token". Example: https://user-images.githubusercontent.com/1752195/228923168-cc8b2f9c-a67a-4771-87f3-6bfa448ca688.png

Add this value, and optionally a fallback channel, to your services.php config file:

    'slack' => [
        'notifications' => [
            'bot_user_oauth_token' => env('SLACK_BOT_USER_OAUTH_TOKEN'),
            'channel' => env('SLACK_BOT_USER_DEFAULT_CHANNEL'),
        ],
    ],

I did not create a default config/publisher for this, as I don't want to override what the user already has. Not sure what the best approach would be, but (obviously) feel free to adjust how this works if you have a better idea :)

Usage

Write your notification:

<?php

namespace App\Notifications;

use Illuminate\Notifications\Notification;
use Illuminate\Notifications\Slack\BlockKit\Blocks\ActionsBlock;
use Illuminate\Notifications\Slack\BlockKit\Blocks\ContextBlock;
use Illuminate\Notifications\Slack\BlockKit\Composites\ConfirmObject;
use Illuminate\Notifications\Slack\SlackMessage;
use Illuminate\Support\Facades\App;

class BlockKitBasedNotification extends Notification
{
    /**
     * Get the notification channels.
     *
     * @param  mixed  $notifiable
     * @return array|string
     */
    public function via($notifiable)
    {
        return ['slack'];
    }

    /**
     * Get the Notification as a Slack message.
     */
    public function toSlack(object $notifiable): SlackMessage
    {
        return (new SlackMessage())
            ->username('LaraSlackNotifier')
            ->to('#general')
            ->text('This is the fallback notification message')
            ->headerBlock('But first, this message from our sponsor')
            ->actionsBlock(function (ActionsBlock $block) {
                $block->button('Click me!')
                    ->url('https://laravel.com')
                    ->danger()
                    ->confirm('This action can only be undone by gnomes.', function (ConfirmObject $dialog) {
                        $dialog->confirm('You gnome it!');
                        $dialog->deny('Oh no, gnomes!');
                    });
            })
            ->contextBlock(function (ContextBlock $block) {
                $block->image('https://upload.wikimedia.org/wikipedia/commons/thumb/9/9a/Laravel.svg/1280px-Laravel.svg.png')->alt('The Laravel Logo');
                $block->text('Laravel v' . App::version());
            })
            ->dividerBlock()
            ->imageBlock('https://laravel.com/img/og-image.jpg', 'Laravel Homepage Image');
    }
}

Here's what this Notification will generate:

Then, there's a couple of ways to route the notification when using direct routes:

• Using the config settings (or what's defined in the notification itself). This requires the OAuth token to be set in the config:

  Notification::route('slack', null)->notify(new BlockKitBasedNotification());

• Using the OAuth token from the config, and a string-based channel. This overrides the channel defined in the notification:

  Notification::route('slack', '#general')->notify(new BlockKitBasedNotification());

• Using A SlackRoute object:

  use Illuminate\Notifications\Slack\SlackRoute;
  
  Notification::route('slack', SlackRoute::make('channel', 'token'))->notify(new BlockKitBasedNotification());

In the SlackRoute object example, either value is optional/nullable, but this effectively allows you to customize both the OAuth Token, as well as the channel.

Extras

If you quickly want to see what blocks you've been building, you can chain the dd() call on the end of the SlackNotification. This will generate and dump an URL to the BlockKitBuilder, which then previews the payload + the notification itself in your browser. For example, here's the URL to the notification above

If you instead just want the original dd() method and dump the whole payload, you can pass true to the dd() call.

Notes

• This doesn't implement all the blocks/elements, just the ones that are useful for regular send-and-forget type notifications. They could be extended (e.g. you could add text fields or dropdown menus) to write complete Laravel-based Slack bots.
• This replaces the Webhook's "Attachments".
• This drops support for EOL Laravel apps (<= Laravel 8) and associated PHP versions (<= 7.x)

[driesvints]

@claudiodekker I merged 2.0 into master so it's up to date. Can you resent this PR with a clean commit history? Thanks!