mcrumm/phlack

Slack API and WebHook integration in PHP

Installs: 9 482

Dependents: 0

Stars: 22

Watchers: 4

Forks: 3

Open Issues: 1

Language: PHP

v0.5.5 2015-07-19 23:36 UTC

README

Build Status Scrutinizer Quality Score Code Coverage Total Downloads Latest Stable Version Latest Unstable Version License

Phlack eases the creation of Slack Integrations in PHP.

Update: Phlack now contains a partial implementation of the Slack API. For details, see the API Docs section below.

Installation & Configuration

Installation

via Composer

{
    "require": {
        "mcrumm/phlack": "dev-master"
    }
}

Configuration

Create a hash containing your slack username and integrations token.

Your username is the unique portion of your Slack subdomain. For example, if your subdomain was groundctrl.slack.com, your username will be groundctrl.

<?php
$config = [ 'username' => 'my_slack_user', 'token' => 'my_slack_token' ]);

Usage

Getting Phlack

Get a Phlack object by instantiating it with a PhlackClient or using its static factory() method.

via factory():
<?php
//...
use Crummy\Phlack\Phlack;
$phlack = Phlack::factory($config);
via new Phlack():
<?php
use Crummy\Phlack\Bridge\Guzzle\PhlackClient;
use Crummy\Phlack\Phlack;

$client = PhlackClient::factory($config);
$phlack = new Phlack($client);
:heart: for Guzzle

The PhlackClient is simply a web service client implemented with Guzzle. Examine its service description for more details.

Creating Messages

A Phlack Message takes care of structuring the payload for Slack's Incoming Webhooks integration.

via new Message();
<?php
//...
use Crummy\Phlack\Message\Message;
$message = new Message('Hello, from phlack!');
echo 'The message payload: ' . PHP_EOL:
echo $message;

via the MessageBuilder

A MessageBuilder is also provided:

<?php
// ...
$messageBuilder = $phlack->getMessageBuilder();
$messageBuilder
  ->setText('I was created in the MessageBuilder')
  ->setChannel('testing')
  ->setIconEmoji('ghost');
$message = $messageBuilder->create();

Sending Messages

Use Phlack's send() command to fire off the message:

<?php
// ...
$response = $phlack->send($message);

if (200 != $response['status']) {
  die('FAIL! - ' . $response['text']);
}

echo 'The message was sent: ' . $message;
Response

The MessageResponse hash contains the status, reason, and text from the response.

Responses from the Incoming Webhooks Integration are very sparse. Success messages will simply return a status of 200. Error messages will contain more details in the response text and reason.

More Examples

See the examples directory for more use cases.

Slack API

Programmatic access to the Slack API is provided via the ApiClient.

Note: Currently, bearer token authentication is the only supported authentication method. Contributions toward OAuth2 support would be greatly appreciated.

Getting a Client

Get an ApiClient object by instantiating it with a hash containing your API token, or passing a config hash to its factory method.

via factory():
<?php

use Crummy\Phlack\Bridge\Guzzle\ApiClient;

$slack = ApiClient::factory([ 'token' => 'my_bearer_token' ]);
via new ApiClient():
<?php

use Crummy\Phlack\Bridge\Guzzle\ApiClient;

$slack = new ApiClient([ 'token' => 'my_bearer_token' ]);

Methods

The methods currently implemented are:

Consult the client's service description for information on the responses returned by the API methods.

Example: Listing all Channels
<?php

use Crummy\Phlack\Bridge\Guzzle\ApiClient;

$config = [ 'token' => 'my_bearer_token' ];
$slack = new ApiClient($config);

echo 'Fetching Channels List...' . PHP_EOL;
$result = $slack->ListChannels();

if (!$result['ok']) {
    die('FAIL! Error was: ' . $result['error'] . PHP_EOL);
}

foreach ($result['channels'] as $channel) {
    printf('%s: %s' . PHP_EOL, $channel['name'], $channel['purpose']['value']);
}

Iterators

Example: ListFilesIterator

The ListFilesIterator eases the ability to iterate through multiple pages of data from the Slack API. Using the iterator eliminates the need to manually call the API multiple times to retrieve all pages of the result set.

<?php
//...
$iterator = $slack->getIterator('ListFiles');

$i = 0;
foreach ($iterator as $file) {
    $i++;
    echo $file['title'] . PHP_EOL;
}

echo PHP_EOL . 'Retrieved ' . $i . ' files.' . PHP_EOL;

A complete example is available in the examples directory.

Note: The ListFilesIterator is not strictly necessary to page through file results, but it's certainly easier than the alternative. An example without the iterator is also available.

More Examples

See the API examples directory for more use cases.

Disclaimer

Any undocumented portion of this library should be considered EXPERIMENTAL AT BEST. Proceed with caution, and, as always, pull requests are welcome.

Acknowledgements

  1. The regex in the LinkFormatter was pulled directly from StevenSloan and his slack-notifier project.