Skip to content

Commit 30ff7de

Browse files
maknzmaknz
committed
Rework the send method and implement attachments and icons
Rather than bogging down the send() function, we now have nice chainable methods for setting the username, channel and icon. The send function is now used to send the composed message along with the text for the message. Also implemented some unit testing.
1 parent 51ec1ec commit 30ff7de

13 files changed

+1379
-132
lines changed

‎.travis.yml

-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
language: php
22

33
php:
4-
- 5.3
54
- 5.4
65
- 5.5
76
- 5.6

‎README.md

+177-16
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,31 @@
11
# Slack
22

3-
A simple Laravel package for sending messages to [Slack](https://slack.com) with [incoming webhooks](https://my.slack.com/services/new/incoming-webhook).
3+
A simple PHP package for sending messages to [Slack](https://slack.com) with [incoming webhooks](https://my.slack.com/services/new/incoming-webhook), focussed on ease-of-use and elegant syntax. Includes Laravel 4 support out of the box.
44

55
## Requirements
66

77
* PHP 5.4 or greater
8-
* Laravel 4.1 or greater
8+
9+
## Contributors
10+
11+
I will happily look at any pull requests or suggestions to improve the package and provide attribution for your contributions. Help share the improvements with everyone!
12+
13+
* [@maknz](https://github.com/maknz)
14+
* [@willwashburn](https://github.com/willwashburn)
915

1016
## Installation
1117

1218
You can install the package using the [Composer](https://getcomposer.org/) package manager. Assuming you have Composer installed globally:
1319

1420
```sh
15-
composer require maknz/slack:0.1.*
21+
composer require maknz/slack:0.2.*
1622
```
1723

18-
### Service provider and alias
24+
## Laravel 4
1925

20-
Next, add the `Maknz\Slack\SlackServiceProvider` service provider to the `providers` array in your `app/config.php` file.
26+
We include a Laravel 4 facade which provides a nicer syntax for using the client and allows for automatic configuration of username, channel and icon.
27+
28+
Firstly, add the `Maknz\Slack\SlackServiceProvider` service provider to the `providers` array in your `app/config.php` file.
2129

2230
```php
2331
'providers' => array(
@@ -43,27 +51,180 @@ Publish the configuration with
4351
php artisan config:publish maknz/slack
4452
```
4553

46-
This 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](https://my.slack.com/services/new/incoming-webhook). The URL will be available under the "Instructions for creating Incoming WebHooks" panel. You can also configure the default channel and username in the config file.
54+
This 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](https://my.slack.com/services/new/incoming-webhook). The URL will be available under the "Instructions for creating Incoming WebHooks" panel. You can also configure the default channel, username and icon in the config file.
4755

48-
You can change the icon that will be used when editing the webhook in the Slack backend.
56+
You can change the default icon to be used in the Slack backend, or it can be changed to a URL or emoji client-side.
4957

5058
## Usage
5159

60+
### Using Laravel
61+
62+
#### Sending a message using the defaults in the config
63+
5264
```php
53-
// Sending a message using the defaults in the configuration
5465
Slack::send('Hello world!');
66+
```
67+
68+
#### Sending a message to a different channel
69+
```php
70+
Slack::to('#accounting')->send('Are we rich yet?');
71+
```
72+
73+
#### Sending a message to a user
74+
```php
75+
Slack::to('@regan')->send('Yo!');
76+
```
77+
78+
#### Sending a message to a channel as a different username
79+
```php
80+
Slack::from('Jake the Dog')->to('@FinnTheHuman')->send('Adventure time!');
81+
```
82+
83+
#### Sending a message with a different icon
84+
```php
85+
// Either with a Slack emoji
86+
Slack::to('@regan')->withIcon(':ghost:')->send('Boo!');
87+
88+
// or a URL
89+
Slack::to('#accounting')->withIcon('http://example.com/accounting.png')->send('Some accounting notification');
90+
```
91+
92+
#### Send an attachment
93+
94+
```php
95+
Slack::to('@regan')->attach([
96+
'fallback' => 'It is all broken, man', // Fallback text for plaintext clients, like IRC
97+
'text' => 'It is all broken, man', // The text for inside the attachment
98+
'pretext' => 'From user: JimBob' // Optional text to appear above the attachment and below the actual message
99+
'color' => 'bad', // Change the color of the attachment, default is 'good'
100+
])->send('New alert from the monitoring system');
101+
```
102+
103+
#### Send an attachment with fields
104+
105+
```php
106+
Slack::to('#operations')->attach([
107+
'fallback' => 'It is all broken, man',
108+
'text' => 'It is all broken, man',
109+
'pretext' => 'From user: JimBob'
110+
'color' => 'bad',
111+
'fields' => [
112+
[
113+
'title' => 'Metric 1',
114+
'value' => 'Some value'
115+
],
116+
[
117+
'title' => 'Metric 2',
118+
'value' => 'Some value',
119+
'short' => true // whether the field is short enough to sit side-by-side other fields, defaults to false
120+
]
121+
]
122+
])->send('New alert from the monitoring system');
123+
```
124+
125+
### Chaining
126+
127+
All setter-like methods are chainable, so rather than having to type:
128+
129+
```php
130+
$client->from('Username');
131+
132+
$client->to('@regan');
133+
134+
$client->send('A message');
135+
```
136+
137+
The method calls can be chained together:
138+
139+
```php
140+
$client->from('Username')->to('@regan')->send('A message');
141+
```
142+
143+
### Usage outside of Laravel
144+
145+
All the same methods from the Laravel examples apply, the only difference is needing to instantiate a client manually.
146+
147+
You will need to `use` the Client at the top of your class:
148+
149+
```php
150+
use Maknz\Slack\Client;
151+
```
152+
153+
#### Send using the class defaults
154+
155+
This example sends 'Yo!' to #general as the user 'Robot', with the default webhook icon that Slack provide.
156+
157+
```php
158+
$client = new Client('http://the.slack.endpoint');
159+
160+
$client->send('Yo!');
161+
```
162+
163+
#### Instantiate the client with config/defaults
164+
165+
This example changes the default username, channel and icon from the class defaults. This is how the Laravel service provider works to set the defaults from the configuration file.
166+
167+
```php
168+
$config = [
169+
'username' => 'The Website Bot',
170+
'channel' => '#operations',
171+
'icon' => ':heart_eyes:'
172+
];
173+
174+
$client = new Client('http://the.slack.endpoint', $config);
175+
176+
$client->send('Test message');
177+
```
178+
179+
### Changing the config on the fly
180+
181+
As with the Laravel examples, the config can be changed on the fly.
182+
183+
```php
184+
$client = new Client('http://the.slack.endpoint', ...);
55185

56-
// Sending a message to a specific channel
57-
Slack::send('Hello world!', '#accounting');
186+
$client->from('A username')->to('#channel')->send('Hey');
187+
```
188+
189+
## Advanced usage
58190

59-
// Sending a message to a user
60-
Slack::send('Hello world!', '@maknz');
191+
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 client:
61192

62-
// Sending a message to a channel, overriding the default username
63-
Slack::send('Hello world!', '#general', 'Robot');
193+
```php
194+
$attachment = new Attachment([
195+
'fallback' => 'Some fallback text',
196+
'text' => 'The attachment text'
197+
]);
64198

199+
$client->attach($attachment);
65200
```
66201

67-
## Contributing
202+
Each attachment field is also an object, an AttachmentField. They can be used as well instead of their data in array form:
68203

69-
I will happily look at any pull requests to improve the package and provide attribution for your contributions. Help share the improvements with everyone!
204+
```php
205+
$attachment = new Attachment([
206+
'fallback' => 'Some fallback text',
207+
'text' => 'The attachment text',
208+
'fields' => [
209+
new AttachmentField([
210+
'title' => 'A title',
211+
'value' => 'A value',
212+
'short' => true
213+
]);
214+
]
215+
]);
216+
```
217+
218+
You can also set the attachments and fields directly if you have a whole lot of them:
219+
220+
```php
221+
$client = new Client(...);
222+
223+
$client->setAttachments($bigArrayOfAttachments);
224+
```
225+
226+
```php
227+
$attachment = new Attachment([]);
228+
229+
$attachment->setFields($bigArrayOfFields);
230+
```

‎composer.json

+9-3
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "maknz/slack",
3-
"description": "A simple Laravel 4 package for sending messages to Slack",
3+
"description": "A simple PHP package for sending messages to Slack, with Laravel 4 support",
44
"keywords": ["laravel", "slack"],
55
"license": "BSD-2-Clause",
66
"authors": [
@@ -11,8 +11,14 @@
1111
],
1212
"require": {
1313
"php": ">=5.4.0",
14-
"illuminate/support": "4.*",
15-
"guzzlehttp/guzzle": "~4.0"
14+
"guzzlehttp/guzzle": "~4.0",
15+
"ext-mbstring": "*"
16+
},
17+
"require-dev": {
18+
"phpunit/phpunit": "4.2.*"
19+
},
20+
"suggest": {
21+
"illuminate/support": "Required for Laravel support"
1622
},
1723
"autoload": {
1824
"psr-0": {

0 commit comments

Comments
 (0)