Today I released my first personal project on Github: Toggl Slash Command for Slack.
I like to learn by giving myself projects. I treat them as if I were releasing them to the public, even if I’m going to move on after I’ve learned what I want to learn. This is one of those projects. I created a roadmap of features that I probably won’t ever implement, but I learned a ton getting what I have so far to work, so I’m calling this a win.
What I learned
- How to read from and write to an API
- How to structure complex if/then statements to parse input text
- Dealing with arrays in PHP
- Deeper regex processing
- Unicode conversions
- Releasing code to a public repo on Github
- Designing security measures for a system deployed on the web
- How to structure and design a codebase from scratch
- How to work within the bounds of the different systems you are working in and finding ways around barriers
- Implementing command line options
- Using other projects in your own project via dependency managers like Composer
- Writing documentation
- Show a list of projects and their corresponding IDs in a given workspace
- Show a list of tasks associated with a given project
- Add time entries to Toggl straight from Slack’s message input box
Setup & Installation
- You must have PHP 5.3.2+ installed locally and on an accessible server.
- You need Composer installed locally to install the third-party dependencies.
Two third-party libraries are dependencies included via Composer:
- Clone or download this repository onto your local machine
- Install Composer in this repository if you don’t already have it
- Open a command line terminal and navigate to this directory.
php composer.phar installvia the command line to install the third-party dependencies
Configure the variables file.
- Copy the variables-dist.php file to
- Fill out the Slack token you got while setting up the slash command.
- Fill out users’ Slack usernames with their corresponding Toggl API keys in the array. They can get those keys at the bottom of https://toggl.com/app/profile.
- Enter a workspace ID for your team. to find yours, log in to Toggl, then go to https://www.toggl.com/api/v8/workspaces. Pick the ID of the workspace you want to use. Don’t wrap it in quotes; it needs to be an integer.
- Set your team’s default timezone. Right now it is set to
- Save the file as
variables.phpin the same directory and you are good to go!
Upload to a server with a valid SSL certificate
- Once the dependencies are installed, upload the whole directory to a server running PHP 5.3.2+
- Ensure you have a valid SSL certificate. Slash command URLs must support HTTPS and serve a valid SSL certificate. Self-signed certificates are not allowed. Check out CloudFlare for an easy way to obtain a valid certificate.
Configure a custom slash command on Slack
- Log in to your Slack account and navigate to Custom Integration to set up a custom slash command.
- Click Add Configuration.
- Choose the command you want (I use
- Fill out the path to the
slash_parsing.phpfile on your server from above.
- Set the method to be POST.
- Copy the token and save it for
- Set a fun name and icon. I use Toggl’s logo from their media kit.
/toggl help– Shows the syntax below
/toggl about– Shows info about this slash command and directs people to this repository
/toggl show projects– Shows the list of projects associated with API key of the user the workspace ID set in
/toggl show tasks [project ID]– Shows a list of tasks associates with a given project ID.
/toggl show tasks 10692310
/toggl add -p [project ID] -d "description" -t [duration in hh:mm:ss]– Adds a time entry to Toggl. Don’t include the [ ].
add -d "Weekly check-in" -p 10692310 -t 00:15:00
- Additional options:
--date [mm/dd/yy]– Adds the time entry to a specific date. If none is passed, it defaults to today’s date.
--task [task id]– Adds the time entry to a task ID. See above to find your task ID for a project.
- I added basic logging to CSV for usage stats and debugging. This happens individually per project, stored in
log.csv. Nothing is transmitted back to me.
- If you’d prefer to not log usage, simply comment out lines 14-19 in
- Since the log includes a Slack token, you’ll want to deny access to
log.csvon your webserver. I achieved that via my