I’ve been toying around with Slackbots a bit lately. Back in January I wrote about publishing a Git log to Slack via one. They’re dirt simple to implement and can be really useful.
They can also be fun. I’ve added a couple bots in our office Slack just for posting randomness, running as cron jobs. I figured I’d take a look at them here.
A couple weeks ago one of my coworkers posted a link to the documentation for a seemingly-random PHP function in our dev Slack channel. It wasn’t random, it just pertained to an offline conversation, but we still made some cracks about how he was doing it to spread awareness of the function.
At nearly the same time, he and I both said, “That sounds like a great idea for a Slackbot.” So I made it, and it looks like this:
As you can see, it’s a little more advanced than just posting a link to a PHP.net URL. If PHP.net had metadata on its pages that allowed for a nice-looking Slack unfurl, I might have just done that. Instead I decided to pull content from the page we’re linking to and make the Slack post a little prettier with it.
So how does that all work?
Simple thing here. Get the defined PHP functions and then start a do…while loop. By using get_defined_functions() I’m limiting what our PHPBot can link to but I figured there are enough functions available there that it doesn’t really matter.
We jump into our do…while loop, where we grab a random function from our array of functions and build what should be a PHP.net documentation URL from the name. For some reason, not every function has documentation (or at least not that matches this template), which is why we’re in a do…while loop.
We get the headers for that URL and if no shorturl is defined there, we know we don’t have a valid function documentation page. In that case, we sleep (I like to sleep in situations like this) and unset the URL, then we’ll take another run at the do…while loop.
If we do have a shorturl, we get into the heavy lifting.
We initialize a couple arrays that we’ll use for building our Slack message, then we pull in the HTML from the documentation page and strip out line breaks and any spaces that might start a line. We do that stripping so that the text we use in our message later on looks better.
Then we load that HTML into a DOMDocument and fire up XPath for it so we can target the elements we want a little easier.
We grab the element of the page that contains all of the information about the function by targeting the refentry class.
Inside that element is a div with class refnamediv, which contains an H1 with the function name, a paragraph classed as verinfo with information about what versions of PHP support the function, and a paragraph defining the function classed as refpurpose. We grab each of these as we’ll use them in our message.
If – for some reason – we didn’t get a function name, we sleep (like I said, I like to sleep in these situations) and then head back to the start of our do…while loop.
Having advanced this far, we target the “Description” section of the function documentation page, which has a class of refsect1 description.
Inside that div is an H3 that serves as the section title, a div that contains an example use of the function, a paragraph with a description, and an optional blockquote with notes about the function. We target each of these and pull that content in, then we use them to build the test of our message.
It should be noted that we use markup to make sure that the example is displayed as a code block while the note(s) (if present) are displayed as a quote, mimicking their appearance on PHP.net.
With all of the information we need acquired, we build our message.
The description section title and our formatted text from it are added as a Slack attachment field. That attachment gets the function name as a title (linked to the documentation URL) and it’s text is the version and purpose text we grabbed early on.
We post this all as user “PHPBot” with a hosted avatar. These two steps aren’t necessary as you can define your incoming webhook’s name and avatar, but we’re reusing a webhook for multiple purposes and, as such, define these for each.
Then we hit the end of our do…while loop. We’ve assembled our message so we can move on.
Lastly, we actually send that message. It’s just a cURL post to the Slack webhook URL (obscured here) and ends up posting a message that looks like this:
As I said, there’s nothing too complex here. If anything, this is probably over-complicated. But it gives us something to talk about at 2:05 every day.
Last week another coworker posted to our developer channel asking that we all send a random photo of a Yak to one of our non-dev coworkers. My immediate thought was that this was begging to be made into a Slackbot, and thus the YakBot was created.
We bring in the Google search API for this one in addition to the Slack API but overall it’s a bit simpler because there’s less of a message to build.
The first thing we do is define our Google search API key and the ID of the custom search engine that we’re using. Then we build an array of possible recipients of our yak. The recipients include our developer channel as well as individual user IDs, to whom the message would be sent in the form of a direct message from Slackbot.
Next we select a random number between 1 and 91. This is because the Google search API won’t let you request a start point higher than 91 for some reason. The search results return ten items, which means the most results you can get is 100. We only need one and one 1/91 is close enough to 1/100 so I do the randomizing up front and then do the lookup and take the first response.
Here we actually do that lookup. We get JSON back and decode it to pull out the first item listed.
Once we have our image URL, we build our message, which is relatively simple compared to the PHPBot message because all we’re doing is posting an attachment with an image. As I mentioned above, we also define a custom username and avatar, though we don’t need to.
Finally, we wrap it up by determining who to send our yak to. We loop through each of our channels and generate a random number between zero and nine. If the number is zero, we add that channel to the list of recipients.
We do that because it allows for some randomness. It’d get noisy if we were posting yaks too often or too regularly.
Then we loop through the list of recipients and send the message, defining the channel along the way. The lucky winners end up getting something like this:
