razorpay/slack

A simple PHP package for sending messages to Slack, with a focus on ease of use and elegant syntax.

Wednesday, May 16, 2018
by captn3m0
Repository
54 Watchers
13 Stars
60,870 Installations

PHP
2 Dependents
0 Suggesters
154 Forks
3 Open issues
36 Versions
24 % Grown

The README.md

Slack for PHP

, _(*1)

A simple PHP package for sending messages to Slack with incoming webhooks, focussed on ease-of-use and elegant syntax., _(*2)

Laravel integration: Slack for Laravel
Symfony integration: NexySlackBundle

Requirements

PHP 5.5, 5.6, 7.0 or HHVM

Installation

You can install the package using the Composer package manager. You can install it by running this command in your project root:, _(*3)

composer require razorpay/slack

Then create an incoming webhook on your Slack account for the package to use. You'll need the webhook URL to instantiate the client (or for the configuration file if using Laravel)., _(*4)

Basic Usage

Instantiate the client

// Instantiate without defaults
$client = new Razorpay\Slack\Client('https://hooks.slack.com/...');

// Instantiate with defaults, so all messages created
// will be sent from 'Cyril' and to the #accounting channel
// by default. Any names like @regan or #channel will also be linked.
$settings = [
    'username' => 'Cyril',
    'channel' => '#accounting',
    'link_names' => true
];

$client = new Razorpay\Slack\Client('https://hooks.slack.com/...', $settings);

Settings

The default settings are pretty good, but you may wish to set up default behaviour for your client to be used for all messages sent. All settings are optional and you don't need to provide any. Where not provided, we'll fallback to what is configured on the webhook integration, which are managed at Slack, or our sensible defaults., _(*5)

Field	Type	Description
`channel`	string	The default channel that messages will be sent to
`username`	string	The default username for your bot
`icon`	string	The default icon that messages will be sent with, either `:emoji:` or a URL to an image
`link_names`	bool	Whether names like `@regan` or `#accounting` should be linked in the message (defaults to false)
`unfurl_links`	bool	Whether Slack should unfurl text-based URLs (defaults to false)
`unfurl_media`	bool	Whether Slack should unfurl media-based URLs, like tweets or Youtube videos (defaults to true)
`allow_markdown`	bool	Whether markdown should be parsed in messages, or left as plain text (defaults to true)
`markdown_in_attachments`	array	Which attachment fields should have markdown parsed (defaults to none)

Sending messages

Sending a basic message (preview)

$client->send('Hello world!');

Sending a message to a non-default channel

$client->to('#accounting')->send('Are we rich yet?');

Sending a message to a user

$client->to('@regan')->send('Yo!');

Sending a message to a channel as a different bot name (preview)

$client->from('Jake the Dog')->to('@FinnTheHuman')->send('Adventure time!');

Sending a message with a different icon (preview)

// Either with a Slack emoji
$client->to('@regan')->withIcon(':ghost:')->send('Boo!');

// or a URL
$client->to('#accounting')->withIcon('http://example.com/accounting.png')->send('Some accounting notification');

Sending a message using Queue


$client->to('#accounting')->withIcon('http://example.com/accounting.png')->queue('Some accounting notification');

Send an attachment (preview)

$client->to('#operations')->attach([
    'fallback' => 'Server health: good',
    'text' => 'Server health: good',
    'color' => 'danger',
])->send('New alert from the monitoring system'); // no message, but can be provided if you'd like

Send an attachment with fields (preview)

$client->to('#operations')->attach([
    'fallback' => 'Current server stats',
    'text' => 'Current server stats',
    'color' => 'danger',
    'fields' => [
        [
            'title' => 'CPU usage',
            'value' => '90%',
            'short' => true // whether the field is short enough to sit side-by-side other fields, defaults to false
        ],
        [
            'title' => 'RAM usage',
            'value' => '2.5GB of 4GB',
            'short' => true
        ]
    ]
])->send('New alert from the monitoring system'); // no message, but can be provided if you'd like

Send an attachment with an author (preview)

$client->to('@regan')->attach([
    'fallback' => 'Keep up the great work! I really love how the app works.',
    'text' => 'Keep up the great work! I really love how the app works.',
    'author_name' => 'Jane Appleseed',
    'author_link' => 'https://yourapp.com/feedback/5874601',
    'author_icon' => 'https://static.pexels.com/photos/61120/pexels-photo-61120-large.jpeg'
])->send('New user feedback');

Advanced usage

Markdown

By default, Markdown is enabled for message text, but disabled for attachment fields. This behaviour can be configured in settings, or on the fly:, _(*6)

Send a message enabling or disabling Markdown

$client->to('#weird')->disableMarkdown()->send('Disable *markdown* just for this message');

$client->to('#general')->enableMarkdown()->send('Enable _markdown_ just for this message');

Send an attachment specifying which fields should have Markdown enabled

$client->to('#operations')->attach([
    'fallback' => 'It is all broken, man',
    'text' => 'It is _all_ broken, man',
    'pretext' => 'From user: *JimBob*',
    'color' => 'danger',
    'mrkdwn_in' => ['pretext', 'text']
])->send('New alert from the monitoring system');

Explicit message creation

For convenience, message objects are created implicitly by calling message methods on the client. We can however do this explicitly to avoid hitting the magic method., _(*7)

// Implicitly
$client->to('@regan')->send('I am sending this implicitly');

// Explicitly
$message = $client->createMessage();

$message->to('@regan')->setText('I am sending this explicitly');

$message->send();

Sending via a queue


// $queue is an instance of Illuminate\Queue\QueueManager
$client = new Razorpay\Slack\Client('http://your.slack.endpoint', $settings, $queue);
$client->to('@regan')->queue('I am sending this implicitly');

If you are using the Laravel service provider, your default queue will be automatically used., _(*8)

Attachments

When using attachments, the easiest way is to provide an array of data as shown in the examples, which is actually converted to an Attachment object under the hood. You can also attach an Attachment object to the message:, _(*9)

$attachment = new Attachment([
    'fallback' => 'Some fallback text',
    'text' => 'The attachment text'
]);

// Explicitly create a message from the client
// rather than using the magic passthrough methods
$message = $client->createMessage();

$message->attach($attachment);

// Explicitly set the message text rather than
// implicitly through the send method
$message->setText('Hello world')->send();

Each attachment field is also an object, an AttachmentField. They can be used as well instead of their data in array form:, _(*10)

$attachment = new Attachment([
    'fallback' => 'Some fallback text',
    'text' => 'The attachment text',
    'fields' => [
        new AttachmentField([
            'title' => 'A title',
            'value' => 'A value',
            'short' => true
        ])
    ]
]);

You can also set the attachments and fields directly if you have a whole lot of them:, _(*11)

// implicitly create a message and set the attachments
$client->setAttachments($bigArrayOfAttachments);

// or explicitly
$client->createMessage()->setAttachments($bigArrayOfAttachments);

$attachment = new Attachment([]);

$attachment->setFields($bigArrayOfFields);

Contributing

If you're having problems, spot a bug, or have a feature suggestion, please log and issue on Github. If you'd like to have a crack yourself, fork the package and make a pull request. Please include tests for any added or changed functionality. If it's a bug, include a regression test., _(*12)

The Versions

16/05 2018

dev-master

9999999-dev

A simple PHP package for sending messages to Slack, with a focus on ease of use and elegant syntax.

library slack

A simple PHP package for sending messages to Slack, with a focus on ease of use and elegant syntax.

razorpay/slack

The README.md

Slack for PHP

Requirements

Installation

Basic Usage

Instantiate the client

Settings

Sending messages

Sending a basic message (preview)

Sending a message to a non-default channel

Sending a message to a user

Sending a message to a channel as a different bot name (preview)

Sending a message with a different icon (preview)

Sending a message using Queue

Send an attachment (preview)

Send an attachment with fields (preview)

Send an attachment with an author (preview)

Advanced usage

Markdown

Send a message enabling or disabling Markdown

Send an attachment specifying which fields should have Markdown enabled

Explicit message creation

Sending via a queue

Attachments

Contributing

The Versions

dev-master

The Requires

The Development Requires

by maknz

by Team Razorpay

dev-laravel5.4

The Requires

The Development Requires

by maknz

by Team Razorpay

1.10.1

The Requires

The Development Requires

by maknz

by Team Razorpay

dev-reduce_job_retry_count

The Requires

The Development Requires

by maknz

by Team Razorpay

1.10.0

The Requires

The Development Requires

by maknz

by Team Razorpay

dev-trusty

The Requires

The Development Requires

by maknz

by Team Razorpay

1.9.9

The Requires

The Development Requires

by maknz

by Team Razorpay

1.9.5

The Requires

The Development Requires

by maknz

by Team Razorpay

1.9.4

The Requires

The Development Requires

by maknz

by Team Razorpay

1.9.3

The Requires

The Development Requires

by maknz

by Team Razorpay

1.9.2