README

Laravel Slack

This package allows you to easily compose and send Slack messages from Laravel applications

Installation

Step-1:

composer require aranyasen/laravel-slack

Step-2: Publish the config:

php artisan vendor:publish --provider=Aranyasen\\LaravelSlack\\SlackServiceProvider

It creates config/laravel-slack.php.

Step-3: Add parameters SLACK_WORKSPACE and SLACK_TOKEN in .env
(See reference below on how to generate a Slack API token)

Usage

// Send a simple message to a channel, say "some-channel"
(new SlackNotification())
    ->channel('some-channel')
    ->text("Hello!")
    ->send();

// Send a section (Ref: https://api.slack.com/reference/block-kit/blocks#section)
(new SlackNotification())
    ->channel('some-channel')
    ->section() // Starts a section
    ->fields() // Starts a field in this section
    ->markdown(":fire: @here This is an emergency :fire:")
    ->endFields()
    ->endSection()
    ->send();

// Send a raw JSON block (example from https://api.slack.com/block-kit/building#block_basics)
(new SlackNotification())
    ->channel('some-channel')
    ->block([
      "type" => "section",
      "text" => [
        "type" => "mrkdwn",
        "text" => "New Paid Time Off request from <example.com|Fred Enriquez>\n\n<https://example.com|View request>",
      ],
    ])
    ->send();

// Compose a message and dump the JSON that'll be sent to Slack. Useful for debugging.
(new SlackNotification())
    ->channel('some-channel')
    ->text("Hello!")
    ->dump();

// Upload a file
(new SlackNotification())
    ->channel('some-channel')
    ->file($filePath, 'Some filename')
    ->upload();

// Optionally, a title, or an accompanying message can be added with a file
(new SlackNotification())
    ->channel('some-channel')
    ->file($filePath, 'Some filename')
    ->withInitialComment('some comment')
    ->withTitle('some title')
    ->upload();

APIs:

channel() -> Channel
header() -> Create a header section
context() -> A small footer text
divider() -> A horizontal line
section() / endSection() --> A section block
lists() -> List of items
field() / endfield() --> Inside section
markdown() -> A markdown block, allowed only inside a section
block() -> Pre-composed block
send() -> Send to Slack
dump() -> Dump the final JSON that'd be sent to Slack API file() -> Upload a file
withInitialComment() -> Add a message with a file upload withTitle() -> Add a title with file upload

Testing:

Invoke SlackNotification::fake() to ensure HTTP requests to Slack are mocked. Internally it uses Laravel's Http::fake(), so all available Http::assert* methods can be used for assertions. Example:

SlackNotification::fake();
(new SlackNotification())
    ->channel('channel-1')
    ->send();
Http::assertSent(static fn(Request $request) => $request['channel'] === 'channel-1');

References:

To create a Slack API token

• Visit https://api.slack.com/apps
• If no app is present, create an app (you may select "from scratch")
• If the app was created earlier, select the app under App Name
• On the left pane, under "Features" click "OAuth & Permissions"
• Under Scopes > Bot Token Scopes, click Add an OAuth Scope
• Add these scopes: chat.write and chat.write.public.
  (note: channels.read, users.read may be needed in future versions of this package, but not now)
• Click "reinstall your app" in the yellow bar that appears above
• In the dropdown "Search for a channel", select a channel. Any channel would do - won't matter now.
• Allow it
• Copy the "Bot User OAuth Token" and share

Links:

• Slack Block reference docs: https://api.slack.com/block-kit
• Emoji cheat-sheet: https://github.com/ikatyang/emoji-cheat-sheet
• Color bar not supported in block kits yet (ref: https://stackoverflow.com/a/74826061/2014868)