Freek.dev

At Spatie we've recently introduced a bot to our Slack chat. We've named him Paolo (after the waiter in our favourite Italian restaurant in Antwerp: La Fontanella Da Enzo). Here's a demo of Paolo (the bot) in action.

Behind the scenes Paolo is powered by a Laravel application that responds to all requests Slack is sending to it. In this post I'd like to explain how you can set up your own Laravel powered Slack bot.

General flow

A message in slack that starts with a slash is called a slash command. Whenever you type in a slash command in Slack channel, an http request will be sent to your Laravel app. You have to respond to that command within 3 seconds. Failing to do some will result in an error being displayed in the channel.

After that initial response you're allowed to send multiple delayed responses. But there are some limitations for delayed responses. You may respond up to 5 times within 30 minutes after the user typed in the slash command on the slack channel. Want to know more about slash commands and how they work, then read this excellent article at Slack's API site.

To make responding to Slack a breeze we're going to used the package our team released a few days ago called spatie/laravel-slack-slash-command.

Setting things up

Before you can get started building our Laravel app, you'll need to set up slash command at Slack.com. Head over to the custom integrations page at Slack.com to get started. There click "Slash commands" and on the next page click "Add configuration". On that screen you can choose a name for your Slack command. In our examples we'll use paolo but you can choose anything that Slack allows.

You should now be on a screen that looks like this:

In the url field you should type the domain name of your Laravel app followed by one or more segments. In the screenshot we've added a slack segment. You can choose any segment you want. Normally the token field should already be filled. And that's all you need to do at Slack.com.

The next thing you'll need to do is to install the spatie/laravel-slack-slash-command package. Let's pull it in via Composer.

composer require spatie/laravel-slack-slash-command

Next, you must install the service provider:

// config/app.php
'providers' => [
    ...
    Spatie\SlashCommand\SlashCommandServiceProvider::class,
];

The configuration file of the package can be published with:

php artisan vendor:publish --provider="Spatie\SlashCommand\SlashCommandServiceProvider" --tag="config"

This is the contents of the published config file:

return [

    /**
     * Over at Slack you can configure to which url the slack commands must be send.  
     * url here. You must specify that. Be sure to leave of the domain name.
     */
    'url' => 'slack',

    /**
     * The token generated by Slack with which to verify if a incoming slash command request is valid.
     */
    'token' => env('SLACK_SLASH_COMMAND_VERIFICATION_TOKEN'),

    /**
     * The handlers that will process the slash command. We'll call handlers from top to bottom
     * until the first one whose `canHandle` method returns true.
     */
    'handlers' => [
        //add your own handlers here


        //this handler will respond with a `Could not handle command` message.
        Spatie\SlashCommand\Handlers\CatchAll::class,
    ],
];

And with that you're ready to respond to http requests coming from Slack.

Setting up your first command handler

Whenever a user types in a slash command Slack will send an http request to the Laravel app. Next, our package will go over all classes in the handlers key of the config file from top to bottom until the first one whose canHandle method returns true. A handler is a class that is responsible for receiving a request from slack and sending a response back.

Let's create our first handler. Handlers must extend Spatie\SlashCommand\Handlers\BaseHandler and implement the two abstract methods from that BaseHandler: canHandle and Handle.

Here's an example.

namespace App\SlashCommandHandlers;

use Spatie\SlashCommand\Request;
use Spatie\SlashCommand\Response;
use Spatie\SlashCommand\Handlers\BaseHandler;

class Hodor extends BaseHandler
{
    /**
     * If this function returns true, the handle method will get called.
     *
     * @param \Spatie\SlashCommand\Request $request
     *
     * @return bool
     */
    public function canHandle(Request $request): bool
    {
        return true;
    }

    /**
     * Handle the given request.
     * 
     * @param \Spatie\SlashCommand\Request $request
     * 
     * @return \Spatie\SlashCommand\Response
     */
    public function handle(Request $request): Response
    {
        return $this->respondToSlack("Hodor, hodor...");
    }
}

This Hodor class will just respond with Hodor, hodor, ... to every request that is sent to it.

You'll need to register this class in the config file.

// app/config/laravel-slack-slash-command
    'handlers' => [
        App\SlashCommandHandlers\Hodor::class,
        ...
    ], 

Let's see that in action.

A slightly more advanced handler

Let's create a slightly more interesting handler. This one that just repeats the command you've sent to it but only if the text after the command starts with repeat.

namespace App\SlashCommandHandlers;

use Spatie\SlashCommand\Request;
use Spatie\SlashCommand\Response;
use Spatie\SlashCommand\Handlers\BaseHandler;

class Repeat extends BaseHandler
{
    public function canHandle(Request $request): bool
    {
        return starts_with($request->text, 'repeat');
    }

    public function handle(Request $request): Response
    {   
        $textWithoutRepeat = substr($request->text, 7)

        return $this->respondToSlack("You said {$textWithoutRepeat}");
    }
}

Let's register this handler as well.

// app/config/laravel-slack-slash-command

    'handlers' => [
        App\SlashCommandHandlers\Repeat::class,
        App\SlashCommandHandlers\Hodor::class,
        ...
    ],    

If you type in /paolo repeat Hi, everybody in a slack channel now, you'll get a response Hi, everybody back. When you type in /poalo bla bla bla you'll get a response Hodor, hodor... because the Hodor handler is the first one which canHandle-method returns true.

Notice that Spatie\SlashCommand\Request being past in canHandle and handle? It contains all data that's being passed by Slack to our Laravel app. These are it's most important properties:

• `command`: the command name without the `/` that the user typed in. In our previous example this would be `paolo`.
• `text`: all text text after the command. In our the example above this would be `repeat Hi, everybody`.
• `userName`: the Slack username of the person that typed in the command
• `userId`: the Slack user id of the person that typed in the command
• `channelName`: the name of the channel where the user typed in the command
• `teamDomain`: the name of the Slack subdomain. So if your team is on `example.slack.com` this would be `example`.

Customizing your response

By default the response will be sent to the user who typed in the original message. If you want the response to be visible to all users in the channel you can do this:

    public function handle(Request $request): Response
    {
        return $this
           ->respondToSlack("Hodor, hodor...")
           ->displayResponseToEveryoneOnChannel();
    }

There are also many formatting options. Take a look at this response on Slack:

$this->respondToSlack()
    ->withAttachment(Attachment::create()
        ->setColor('good')
        ->setText('This is good!')
    )
    ->withAttachment(Attachment::create()
        ->setColor('warning')
        ->setText('Warning!')
    )
    ->withAttachment(Attachment::create()
        ->setColor('danger')
        ->setText('DANGER DANGER!')
    )
    ->withAttachment(Attachment::create()
        ->setColor('#439FE0')
        ->setText('This was a hex value')
    );

There are many more options to format a message. Take a look at Slacks documentation on attachments to learn what's possible.

Using signature handlers

A console command in Laravel can make use of a signature to set expectations on the input. A signature allows you to easily define arguments and options.

If you let your handler extend Spatie\SlashCommand\Handlers\SignatureHandler you can make use of a $signature and the getArgument and getOption methods to get the values of arguments and options.

Let's take a look at an example.

namespace App\SlashCommandHandlers;

use Spatie\SlashCommand\Request;
use Spatie\SlashCommand\Response;
use Spatie\SlashCommand\Handlers\SignatureHandler;

class SendEmail extends SignatureHandler
{
    public $signature = "paolo email:send {to} {message} {--queue}"

    public function handle(Request $request): Response
    {   
        $to = $this->getArgument('to');

        $message = $this->getArgument('message');

        $queue = $this->getOption('queue') ?? 'default';

        //send email message...
    }
}

Notice that there is no canHandle method present in that class. The package will automatically determine that a command /paolo email:send test@email.com hello can be handled by this class.

Sending delayed responses

Remember that restriction mentioned above about the initial response to a slash command. Your Laravel app only has three seconds to respond otherwise an error message will be shown at Slack. After that initial fast response you're allowed to send 5 more responses in the next 30 minutes for the command. These responses are called "delayed responses". We're going to leverage Laravel's queued jobs to send those delayed responses. Please make sure that you've set up a real queue driver in your app, it needs to be something other than sync.

Imagine you need to call a slow API to get a response for a slash command. Let's first create a handler that will send the initial fast response.

namespace App\SlashCommandHandlers;

use Spatie\SlashCommand\Request;
use Spatie\SlashCommand\Response;

class SlowApi extends BaseHandler
{
    public function canHandle(Request $request): bool
    {
        return starts_with($request->text, 'give me the info');
    }

    public function handle(Request $request): Response
    {
        $this->dispatch(new SlowApiJob());

        return $this->respondToSlack("Looking that up for you...");
    }
}

Notice that we're dispatching a job right before sending a response. Behind the scenes Laravel will queue that job.

This is how that SlowApiJob would look like.

namespace App\SlashCommand\Jobs;

use Spatie\SlashCommand\Jobs\SlashCommandResponseJob;

class SlowApiJobJob extends SlashCommandResponseJob
{
    // notice here that Laravel will automatically inject dependencies here
    public function handle(MyApi $myApi)
    {
        $response = $myApi->fetchResponse();

        $this
           ->respondToSlack("Here is your response: {$response}")
           ->send();
    }
}

Notice that, unlike in the Handlers the response is not returned and that send() is called after the respondToSlack-method.

With this in place a quick response Looking that info for you... will be displayed right after the user typed /your-command get me the info. After a little while, when MyApi has done it's job Here is your response: ... will be sent to the channel.

Some useful handlers

The previous examples of this post were quite silly. You'll probably never going to use to handlers in your bot. Let's review a real life example. Our Poalo bot can lookup dns records for a given domain. This is how that looks like in a Slack channel.

This is the actual class that we use in our bot:

namespace App\SlashCommandHandlers;

use Spatie\SlashCommand\Attachment;
use Spatie\SlashCommand\AttachmentField;
use Spatie\SlashCommand\Handlers\SignatureHandler;
use Spatie\SlashCommand\Request;
use Spatie\SlashCommand\Response;

class Dns extends SignatureHandler
{
    protected $signature = 'paolo dns {domain}';

    /**
     * Handle the given request. Remember that Slack expects a response
     * within three seconds after the slash command was issued. If
     * there is more time needed, dispatch a job.
     *
     * @param Request $request
     *
     * @return Response
     */
    public function handle(Request $request): Response
    {
        $domain = $this->getArgument('domain');

        if (empty($domain)) {
            return $this->respondToSlack("You must provide a domain name.");
        }

        $sanitizedDomain = str_replace(['http://', 'https://'], '', strtolower($this->getArgument('domain')));

        $dnsRecords = dns_get_record($sanitizedDomain, DNS_ALL);

        if (!count($dnsRecords)) {
            return $this->respondToSlack("Could not get any dns records for domain {$domain}");
        }

        $attachmentFields = collect($dnsRecords)->reduce(function (array $attachmentFields, array $dnsRecord) {
            $value = $dnsRecord['ip'] ?? $dnsRecord['target'] ?? $dnsRecord['mname'] ?? $dnsRecord['txt'] ?? $dnsRecord['ipv6'] ?? '';

            $attachmentFields[] = AttachmentField::create('Type', $dnsRecord['type'])->displaySideBySide();
            $attachmentFields[] = AttachmentField::create('Value', $value)->displaySideBySide();

            return $attachmentFields;
        }, []);

        return $this->respondToSlack("Here are the dns records for domain {$domain}")
            ->withAttachment(Attachment::create()
                ->setColor('good')
                ->setFields($attachmentFields)
            );
    }
}

In order to get home every member of our team needs to bike a bit. That's why we've also created a command to display a rain forecast. This is what happens when /paolo rain is typed in our slack channels.

This is the class responsible for creating that response.

namespace App\SlashCommandHandlers;

use Spatie\SlashCommand\Attachment;
use Spatie\SlashCommand\Handlers\SignatureHandler;
use Spatie\SlashCommand\Request;
use Spatie\SlashCommand\Response;

class Rain extends SignatureHandler
{
    protected $signature = 'paolo rain';

    /**
     * Handle the given request. Remember that Slack expects a response
     * within three seconds after the slash command was issued. If
     * there is more time needed, dispatch a job.
     *
     * @param Request $request
     *
     * @return Response
     */
    public function handle(Request $request): Response
    {
        return $this
            ->respondToSlack("Here you go!")
            ->withAttachment(
                Attachment::create()->setImageUrl('http://api.buienradar.nl/image/1.0/radarmapbe?width=550')
            );
    }
}

In closing

The spatie/laravel-slack-slash-command package makes is it easy to let a Laravel app respond to a slash command from Slack. If you start using the package, let me know in the comments below what your bot can do. And if you like our package, take a look at this list of Laravel packages we've previously released to see if we've made something that can be of use to you.

Read more

When features get added to PHP there's a lot of discussion first about the new functionality. This is done on the so-called internals mailing list. You can try to follow the discussions via a rather ugly interface at http://news.php.net. The site looks like a very old school web email client where all conversations are just running through each other.

A couple of days ago Matthieu Napoli launched his new site externals.io. This site makes following internals a lot easier. Messages that are part of a conversation are grouped and thus much easier to follow. If you're interested in this you should definitely also check out Made with Love's Why We Can't Have Nice Things project that lists all RFC's and votes.

Read more

At the heart of many modern PHP application there is an IoC Container, short for inversion of control container. When people talk about a "dependency injection container" or a "service container" they mean the same thing. It's purpose is to manage class dependencies. Though the concept is relatively simple, it can come across very confusing if you've never worked with one.

In a new post on his blog Matt Allan builds a simple one from scratch. Check it out if you're struggling with understanding how the IoC container works.

If you are writing modern PHP, you will run across dependency injection a lot. Basically all dependency injection means is that if an object needs something, you pass it in. ... Dependency injection makes your code more flexible and easier to test.

http://mattallan.org/2016/dependency-injection-containers/

EDIT: mattalan.org seems to be down, but you can still view the post in Google's cache.

Read more

Collection master Adam Wathan explains in a new video / blogpost how specify a key when mapping an array to a collection.

Read the full post at: https://adamwathan.me/2016/07/14/customizing-keys-when-mapping-collections/

Read more

Because Laravel comes with excellent scheduling functions out of the box, artisans don't need to edit the crontab often. If you need to do some scheduling manually, here's a little site that can help you write a cron scheduling expression.

http://crontab.guru/

Read more

As a user I've pretty much turned my back to Facebook, but boy must it be interesting to work at that scale. Here's how Facebook built their mobile device lab.

... We needed to be able to run tests on more than 2,000 mobile devices to account for all the combinations of device hardware, operating systems, and network connections that people use to connect on Facebook. Today, in our Prineville data center, we have a mobile device lab — outfitted with a custom-built rack — that allows us to run tests on thousands of phones. The process of building a lab in our data center wasn't a direct path, and we learned a lot along the way...

https://code.facebook.com/posts/300815046928882/the-mobile-device-lab-at-the-prineville-data-center/

I stumbled on this story via Bram.us. Subscribe to the RSS feed of that site if you haven't done so already.

Read more

Frank De Jonge, member of the PHP League and author/maintainer of Flysystem, was facing a world of pain with ElasticSearch. Luckily the story has an happy ending. Read all about his journey on his blog.

For a client project we are using ElasticSearch (ES) as one of our read-models. The use-case was pretty straight forward and the amount of data was super small. However, our problems were pretty big. It got to a point where we had to reboot our cluster periodically to prevent it from crashing. So, what was going on? Let's dig in.

https://blog.frankdejonge.nl/how-a-20mb-data-set-brought-down-a-14gb-elasticsearch-cluster/

Read more

In a new post on his blog Thijs Feryn explains type errors and strict types, both introduced in PHP 7.

PHP 7 has a concept called Type Errors. These errors are thrown on a type mismatch when interacting with functions. They can be caught just like exceptions. I created a video that explains the situation. This blog post goes into more detail and has some code examples.

https://blog.feryn.eu/type-errors-php-7/

Read more

Fred Hébert on his blog:

... sooner or later, people start misinterpreting the original intent and thinking of technical debt the same way you could think about financial debt: a lever to use in order to get something now and then pay the accrued cost progressively over time. This is however not how things feel from the technical person's point of view. ... Rather than focusing on why that is wrong, I want to propose an alternative analogy to describe the reality behind technical debt.

http://ferd.ca/on-technical-debt-shoveling-forward.html

Read more

Rob Allen, an active member of the Zend Framework community, makes the case for giving some love to API errors.

It's not hard to have great error responses; you just need to care. Poor error response cause developers to give up with an API and go elsewhere, so it's a competitive advantage to get this right.

Developers integrating with your API will thank you.

https://akrabat.com/api-errors-are-first-class-citizens

Read more

Nicolas Widart, author of Asgard CMS, created a new package called laravel-modules that can help splitting up a large Laravel app in modules.

On his blog he published an introductory post.

Just imagine having a medium sized application where everything is in the `app/ù folder, worse, every model is in the root of the app folder! At some point you will spend a lot of time looking for things because everything is bunched together.

This is what being modular is trying to resolve. You split of the business logic into different parts, which belongs together. If you're into Domain Driven Design, you can consider a module an aggregate.

Every module has its own routes/controllers/models/views/business logic/etc. Meaning every module contains a group of classes that all are related to each other in some way.

https://nicolaswidart.com/blog/writing-modular-applications-with-laravel-modules

Read more

In my book Joseph Silber is one of the unsung heroes of the Laravel ecosystem. Whenever I open up internals on Larachat or Github he's giving friendly and thoughtful advice. I was happy to learn that Joseph started a blog.

In the first post he goes over all the improvements made to authentication in Laravel 5.3.

Authentication has gotten some nice improvements in 5.3, so let's examine it piece by piece.

• Introducing the authenticate method
• The exception handler's unauthenticated method
• The Authenticate middleware
• Authenticating against multiple guards
• Route model binding and global scopes
• Bonus: the request's expectsJson method

https://josephsilber.com/posts/2016/07/10/authentication-improvements-in-laravel-5-3

If you're looking for a package that can handle roles and abilities in Laravel, be sure to check out his Bouncer package.

Read more

Laravel 5.3, which will be released at this years Laracon US, has some new very handy functionality to work with MySQL 5.7 JSON columns. In a post on his site Matt Stauffer demonstrates the new API.

While Laravel has had the ability to cast your data to and from JSON since version 5.0, it was previously just a convenience—your data was still just stored in a TEXT field. But MySQL 5.7 introduced an actual JSON column type.

Laravel 5.3 introduces a simple syntax for lookups and updates based on the value of specific keys in your JSON columns.

https://mattstauffer.co/blog/new-json-column-where-and-update-syntax-in-laravel-5-3

If you're going to use this functionality, you should also read Mohamed Said's post on how to improve performance by using MySQL generated columns.

JSON columns cannot be indexed. You can work around this restriction by creating an index on a generated column that extracts a scalar value from the JSON column.

http://themsaid.com/laravel-mysql-json-colum-fast-lookup-20160709/

Read more

In a post on his site Mattias Geniar shares how to write for loops in Bash.

Let me first start by saying something embarrassing. For the first 4 or 5 years of my Linux career -- which is nearing 10 years of professional experience -- I never used loops in Bash scripts. Or at the command line.

The thing is, I was a very fast mouse-clicker. And a very fast copy/paster. And a good search & replacer in vim and other text editors. Quite often, that got me to a working solution faster than working out the quirky syntax, testing, bugfixing, ... of loops in Bash.

And, to be completely honest, if you're managing just a couple of servers, I think you can get away with not using loops in Bash. But, once you master it, you'll wonder why you haven't learned Bash for-loops sooner.

https://ma.ttias.be/bash-loop-first-step-automation-linux/

Read more

Ross Tuck gave a one of kind closing keynote at this year's (excellent) Dutch PHP Conference. Clear your schedule for the coming hour and watch the video of the talk with full attention. It's really great.

At the conference there were a lot of talks on events sourcing. The two talks with that subject that stood out for me were Shawn McCool's (where he applied event sourcing to the board game Quantum), and Greg Young's opening keynote. Watch the latter one here:

Read more

Jordi Boggiano investigated if there are pundits actively abusing typos in package names.

Earlier this month an article was published summarizing Nikolai Philipp Tschacher's thesis about typosquatting. In short typosquatting is a way to attack users of a package manager by registering a package with a name similar to a popular package, hoping that someone will accidentally typo the name and end up installing your version of it that contains malware.

... I wanted to take a look at our repository data and see if I could spot any bad actors.

https://seld.be/notes/typo-squatting-and-packagist

Read more