How to develop a Pomodoro application for Slack in PHP

Wednesday, December 16, 2020

Introduction

Slack is one of the most common tools for professional communication and allows integration with multiple applications or plug-ins. An example would be Google Calendar, which allows you to configure it to show the closest meetings in the application itself. Therefore Slack can be considered one of the most important tools for the organisation of a team if it is used in a responsible way.

Introducing the Slack API

Slack has very good documentation of its API, as well as a large community of developers using its application, so if you don't find something or have questions accessing the official Slack website documentation, then you can find it on development forums such as Stack Overflow.

The PHP library

Although we could develop the integration with the Slack API completely from scratch, it is not efficient to reinvent the wheel, as the aim of the article is to have a functional application in a few steps and in a simple way.

Having said that, I introduce you to the library that we are going to use: jolincode/slack-php-api. It is a Composer's library, so we are going to import it into the project using this package management system. It also has quite a few slack methods that can be useful and which are updated periodically.

Cookbook

Ingredients:

Composer
Php
Have a Slack workspace to test

Steps:

Create a new folder where the project will be located.
Run composer init to be able to import the libraries needed for this project.
Import the libraries as described in the Slack library installation manual

Your composer will look something like this:

... 
   "require": {
        "symfony/http-client": "^5.2",
        "nyholm/psr7": "^1.3",
        "jolicode/slack-php-api": "^3.0",
    }

Copy this snippet into a file pomodoro.php in the root of the project. For example:

<?php

require __DIR__ . '/vendor/autoload.php';

use JoliCode\Slack\ClientFactory;
use JoliCode\Slack\Exception\SlackErrorResponse;

// Slack Token.
$user_token = 'xoxp-XXXX-XXXX-XXXX-XXXX';
$client = new ClientFactory($user_token);
try {
  $status = [
    // Status message.
    "status_text" => 'Pomodoro time!!',
    // Status icon.
    "status_emoji" => ':tomato:',
    // Status duration.
    "status_expiration" => strtotime('+25 minutes'),
  ];
  $status_json = json_encode($status);
  $result = $client->usersProfileSet([
    "profile" => $status_json,
  ]);

  echo 'Status updated.' . PHP_EOL;
} catch (SlackErrorResponse $e) {
  echo 'Failure.', PHP_EOL, $e->getMessage() . PHP_EOL;
}

Replace the example "user_token" 'xoxp-XXXX-XXXX-XXXX-XXXX' with the one generated in the next step (get the user token).

Get a user token in Slack

These are the steps to obtain the token of the user currently registered in Slack, so it will not be possible to overwrite the status of other users by following these steps.

Go to the Slack API with you slack user and then go to "Your apps"
Create a new application by clicking on the button "Create New App"
After creating the application, go to a "Features/OAuth & Permissions" on the left sidebar.
Go to "User Token Scopes" and add the permission "users.profile:write" click the button "Add an OAuth Scope". This permission is what will allow the application to overwrite the user status.
Select "Settings/Install App" and choose a workspace to install the application.
After installing the application you will get an "OAuth Access Token" that will be something like:
```
xoxp-XXXX-XXXX-XXXX-XXXX
```

Execute the PHP script

If you already have PHP installed on your computer, remember to add the Slack token to the previous PHP snippet in order to update the profile.

All you have to do is run the script from a Bash console.

bash$ php /SCRIPT_DIRECTORY/pomodoro.php

You will see that your profile status has been updated, both the message and the icon temporarily if everything went well.

Conclusions

Now that you know about the Slack library, I invite you to try different methods, for example, sending a message to a specific channel. You can also try to create a bot, although you will need to have a server where it is hosted.

Remember that depending on the methods you use you will have to grant specific permissions to the application and you will have to reinstall it in the workspace. For example, if I go to the method for sending a message in the chat we will see that the scope required for the user is chat:write.

Potential improvements

You have learned to change your profile status in Slack, but the Slack application also allows you to do certain actions under certain commands that you type in the chat called slash commands, with that you could create a command so in the case of writing /pomodoro start for example, change the profile status.