cian/slack

A PHP package for sending messages to Slack.

1.2.0 2020-11-09 16:06 UTC

Requires

• php: >=7.0
• guzzlehttp/guzzle: >=6.0
• illuminate/support: ^5|^6|^7|^8

Requires (Dev)

• mockery/mockery: ^1
• phpunit/phpunit: ^5

MIT

• Cian.h

• php
• slack

README

Requirements

• PHP 7.0+

Installation

composer require cian/slack

Laravel

php artisan vendor:publish --provider="Cian\Slack\LaravelServiceProvider"

If your laravel version <= 5.4, don't forget to add a service provider.

// /config/app.php
[
    "providers" => [
        // other providers ...
        Cian\Slack\LaravelServiceProvider::class
    ]
]

Slack Methods

Slack has a lot of useful methods.

Available methods

• users.list
• users.lookupByEmail

More methods will be added in this library.

users.list

use Cian\Slack\SlackMethod;

$token = 'your-app-token';

$response = (new SlackMethod)
    ->setToken($token)
    ->usersList();

users.lookupByEmail

use Cian\Slack\SlackMethod;

$token = 'your-app-token';

$response = (new SlackMethod)
    ->setToken($token)
    ->usersLookupByEmail($email);

Note that if you get SlackMethod, InteractiveMessage from LaravelServiceProvider,
you don't need to call setToken before api call.

IncomingWebhook

This is an example for sending a basic incoming webhook.
For more complex scenarios you will need to use BlockBuilder or AttachmentBuilder.

use Cian\Slack\IncomingWebhook;

$url = 'https://hooks.slack.com/services/path/to/your/incoming-webhook/url';

(new IncomingWebhook)->send($message, $url);

Interactive Message

To use interactive message, you need to set up OAuth & Permissions of your app. After that, you can send the message like below.

use Cian\Slack\InteractiveMessage;

$token = 'your-app-token';

// $channel can be channel_name, channel_id, user_slack_id
// but Slack suggests not to use channel_name.
$channel = 'development';

$message = 'Hello Interactive Message!';

(new InteractiveMessage([
    'token' => $token,
    'channel' => $channel
]))->send($message);

// or

(new InteractiveMessage)
    ->setToken($token)
    ->to($channel)
    ->send($message);

Block

Slack suggests to use Block instead of Attachment
because Block is more flexible than Attachment.

use Cian\Slack\IncomingWebhook;
use Cian\Slack\Builders\BlockBuilder;

$url = 'https://hooks.slack.com/services/path/to/your/incoming-webhook/url';

$builder = (new BlockBuilder)
    ->section('*A Title Here*')
    ->section('body content ...')
    ->divider()
    ->section('😗😗😗');

(new IncomingWebhook)->send($builder, $url)

Attachment

Even Slack suggests to use Block instead of Attachment,
it won't remove the Attachment.

Attachment has a lot of fields, but they are all legacy.
check slack attachment document to know more

The best way of using Attachment is keep only two fields, blocks and color.

use Cian\Slack\IncomingWebhook;
use Cian\Slack\Builders\BlockBuilder;
use Cian\Slack\Builders\AttachmentBuilder;

$blockBuilder = (new BlockBuilder)->section('How are you?');

// when you provide block builder as the first argument
// the second argument color will be applied
// the color can be 'good', 'warning', 'danger' or any valid hex color code.
$attachments = (new AttachmentBuilder($blockBuilder, '#ff0000'));

$url = 'https://hooks.slack.com/services/path/to/your/incoming-webhook/url';

(new IncomingWebhook)
    ->send($attachments, $url);

Let's say if you still need legacy fields,
you can do it like below.

use Cian\Slack\IncomingWebhook;
use Cian\Slack\Builders\AttachmentBuilder;

$attachments = (new AttachmentBuilder)->add([
    'text' => '😗😗😗',
    'fallback' => 'fall back text...',
    'footer' => 'footer text...',
    'color' => 'danger'
    // ... more legacy fields
]);

$url = 'https://hooks.slack.com/services/path/to/your/incoming-webhook/url';

(new IncomingWebhook)
    ->send($attachments, $url);

Let's say you are facing a very complex scenario,
you would need to use blocks and attachments together.

use Cian\Slack\Message;
use Cian\Slack\IncomingWebhook;
use Cian\Slack\Builders\BlockBuilder;
use Cian\Slack\Builders\AttachmentBuilder;

$titleBlocker = (new BlockBuilder)
    ->section('Title row 😗😗😗');

$bodyBlocker = (new BlockBuilder)
    ->section('body content ...')
    ->divider();

$attachmenter = (new AttachmentBuilder($bodyBlocker, '#ff00ff'));

$message = new Message($titleBlocker);

$message->setAttachments($attachmenter);

$url = 'https://hooks.slack.com/services/path/to/your/incoming-webhook/url';

(new IncomingWebhook)
    ->send($message, $url);

Although I use IncomingWebhook in document examples,
it can be replaced by InteractiveMessage.

Interactive Component

Button

use Cian\Slack\IncomingWebhook;
use Cian\Slack\Builders\BlockBuilder;
use Cian\Slack\Builders\ElementBuilder;

$text = 'Approve';
$actionId = 'approve_request';
$value = ['foo' => 'bar'];  // optional default ''
$style = 'primary';         // optional default 'primary'
$type = 'plain_text';       // optional default `plain_text`
$button = ElementBuilder::makeButton($text, $actionId, $value, $style, $type);
// or $button = (new ElementBuilder)->button(/** same as makeButton */);

$blocker = (new BlockBuilder)
    ->section('*Can I buy a toy ?*')
    ->divider()
    ->actions([$button]);

$url = 'https://hooks.slack.com/services/path/to/your/incoming-webhook/url';

(new IncomingWebhook)->to($url)->send($blocker);
// or (new IncomingWebhook)->send($blocker, $url);