A simple PHP package for sending messages to Slack with incoming webhooks, focussed on ease-of-use and elegant syntax. Includes Laravel support out of the box.
- PHP 5.4 or greater
You can install the package using the Composer package manager. You can install it by running this command in your project root:
composer require maknz/slack:~1.0We include a Laravel 4 service provider which provides a nicer syntax for using the client and allows for setting defaults from a config file.
Firstly, add the Maknz\Slack\SlackServiceProvider service provider to the providers array in your app/config.php file.
'providers' => array(
...
'Maknz\Slack\SlackServiceProvider',
),and then add the facade to your aliases array in your app/config.php file.
'aliases' => array(
...
'Slack' => 'Maknz\Slack\Facades\Slack',
),Publish the configuration with
php artisan config:publish maknz/slackThis will add the boilerplate configuration to app/config/packages/maknz/slack/config.php. You need to add the URL to the webhook the package should use. If you haven't already created an incoming webhook for the package to use, create one in your Slack backend. The URL will be available under the Setup Instructions panel. You can also configure the default channel, username and icon in the config file.
If null is set for channel, username or icon, the defaults set up on the Slack webhook will be used.
If you are using the package in Laravel, you can skip this section as the client is instantiated for you.
// Instantiate without defaults
$client = new Maknz\Slack\Client('http://your.slack.endpoint');
// Instantiate with defaults, so all messages created
// will be sent from 'Archer' and to the #accounting channel
// by default
$settings = [
'username' => 'Archer',
'channel' => '#accounting'
];
$client = new Maknz\Slack\Client('http://your.slack.endpoint', $settings);To send messages, you will call methods on your client instance, or use the Slack facade if you are using the package in Laravel.
// With an instantiated client
$client->send('Hello world!');
// or the Laravel facade
Slack::send('Hello world!');// With an instantiated client
$client->to('#accounting')->send('Are we rich yet?');
// or the Laravel facade
Slack::to('#accounting')->send('Are we rich yet?');$client->to('@regan')->send('Yo!');$client->from('Jake the Dog')->to('@FinnTheHuman')->send('Adventure time!');// 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');$client->to('@regan')->attach([
'fallback' => 'It is all broken, man', // Fallback text for plaintext clients, like IRC
'text' => 'It is all broken, man', // The text for inside the attachment
'pretext' => 'From user: JimBob' // Optional text to appear above the attachment and below the actual message
'color' => 'bad', // Change the color of the attachment, default is 'good'
])->send('New alert from the monitoring system');$client->to('#operations')->attach([
'fallback' => 'It is all broken, man',
'text' => 'It is all broken, man',
'pretext' => 'From user: JimBob'
'color' => 'bad',
'fields' => [
[
'title' => 'Metric 1',
'value' => 'Some value'
],
[
'title' => 'Metric 2',
'value' => 'Some value',
'short' => true // whether the field is short enough to sit side-by-side other fields, defaults to false
]
]
])->send('New alert from the monitoring system');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.
// 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();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:
$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:
$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:
// implicitly create a message and set the attachments
$client->setAttachments($bigArrayOfAttachments);
// or explicitly
$client->createMessage()->setAttachments($bigArrayOfAttachments);$attachment = new Attachment([]);
$attachment->setFields($bigArrayOfFields);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.