Eloquent style Slack API

Tips and advice on how to put the Slack API to good use for development teams.

Share

Recently we started using the awesome service Slack. Being a developer, the first thing I did was delve into the Slack API to see what stuff I can do with it. Turns out, you can do a lot! Today I will talk about what I did with Slack API and how you can use it.

What I did

The first thing I did was dig into the integrations documentation. The best thing to do when getting into an API, I believe, is to always start with the documentation then go from there. There were a few things of note that I could see on the integrations page, ‘Incoming Webhooks’, ‘Outgoing Webhooks’ and ‘Slack API’. After a very quick preliminary read of all three of them I realised exactly what I needed. ‘Incoming Webhooks’ is (pretty much) useless when you compare it with ‘Slack API’ and ‘Outgoing Webhooks’ is basically the thing to go to for recieving real-time data from Slack.

I learned two things from this: ‘Slack API’ is for sending data to Slack and requesting data from Slack. ‘Outgoing Webhooks’ is for recieving live textual data (only if matching a prefix, E.G: ‘!Test’ matches ‘!’ so send it to X-URL).

Initially, I created a simple API passthrough for sending simple data to Slack via specific commands (slack_sendMessage, slack_getChannels etc). This was for testing purposes and allowed me to learn how Slack handled things such as malformed input, errors etc. This is when it came to me to start building a nice PHP API which did something the other PHP implementations (listed by Slack themselves) did not. That is, allow simple and common ways to send api requests and recieve the output without the need of specific functions (E.G: Slack::sendMessage($from, $message, $channel)).

When it came to creating this implementation, I started by writing on a whiteboard how I expect to use it. It started as something like Slack::call($command)->withParameters($data)->getResponse() (note the way I named it, I did this so I could not forget what it did). This is a great way to remember how you expect to use an API so you know how to implement it (when you’re implementing it). My goal with this sort of flow is an Eloquent ORM (as used in Laravel) style of query building.

Next thing I though about is how I expect people to be able to implement this into their own projects, my first and only thought was PSR-4 autloading with Composer. This sets me out a nice file structure (VENDOR/LIBRARY/, in this case: ConnorVG/Slack/). This is great for my target use of it, Laravel. This also means I need to create a Facade and ServiceProvider (for standard reasons) if I wish to utilise Laravel correctly. In doing this, I need to ensure that I am not making the API depend on Laravel. There is no need for this to happen.

Class structure is a big part of development, a friendly framework to work with is a fun framework to work with. With what I have already set, a lot of the structure is much easier to think of. I need methods for building a url for Slack’s API, getting a webpage’s contents, posting data to a webpage and urlifying all data to be passed to the API. These are very standard use functions and are not scope related, hence we make them static. On top of these, we add some convenience methods, stuff like checking if a command is supported, checking if a command should have default params, checking if a command execution errored etc… These are all, also, static.

When it comes to the bare bones OOP based structure, the only methods we actually need to be non-static are methods that require object-scope. Such as methods that actually require the API Key or the instance (for passing to anything outside of the instance that needs to keep a reference of the main Slack instance). These methods are extremely simple.

‘send’ is where we do the sending of the data. It builds the url based on the payload’s command and data, json_encodes the data for it to be compliant with Slack’s API. It then sends the request to Slack’s API and returns the response.

‘prepare’ is where we build the SlackPayload instance based on the command passed, we also need to check if said command is supported and if it should have default params, then return it.

With this API, what I did was use it with my WholeTextFunction API (will release at a later date, keep your eyes open) of which you can pass params to an ‘Outgoing Webhook’ and then my server responds (using my Slack API implementation) with the intended response. An example use is:

A user types !echo Hello! and then a bot called ‘Echo Bot’ will reply with ‘@commandUser Hello!’.

A user types !wolframalpha 5! and then a bot called ‘Wolfram|Alpha’ will reply with the data sent by Wolfram in multiple lines (dependant on the response). This is handled by my Wolfram|Alpha API (will release at a later date, keep your eyes open).

How you can do it

Simply put, using Composer, all you need to do is grab the package ConnorVG/PHP-Slack. There is a great bit of info in the Project’s README.md (at https://github.com/ConnorVG/PHP-Slack) tell you how to get started.


Interested in learning more about enterprise WordPress?
Get in touch with the team today