I was recently tinkering with chat bots in PHP and stumbled across the BotMan library and thought it was so awesome that I'd share it with you all.

What is BotMan?

BotMan.io is an awesome PHP chatbot framework invented by Marcel Pociot.

What makes BotMan so awesome is that it is a framework agnostic library that simplifies the task of bot creation by providing multiple core concepts around bots such as
message handling, attachments, event handling and listening. BotMan also provides a number of messaging platform integrations out of the box such as
Slack, WeChat, Facebook Messenger, HipChat, Telegram etc...

BotMan is obviously built in PHP and is framework agnostic however we are going to look at BotMan Studio which is a boilerplate project that does utilize BotMan with the awesome Laravel package. If you wish to follow this tutorial
but not use Laravel then look at the docs here and look at Basic Usage without BotMan studio and get that setup with composer in order to follow along.

Ok, ok. How do I install it?

As mentioned we will be using BotMan Studio in order to get started quickly with BotMan and Laravel.

The first step is to install composer - you can find the installation instructions here if you don't have it.

Once installed, we will use composer to install the BotMan CLI tool globally:

composer global require "botman/installer"

Once installed, we can create a new BotMan app using the BotMan CLI. For this tutorial, we will be writing a small "Hello World" bot so let's get started with that.

botman new helloworldbot

If everything installs correctly you will see:

BotMan Studio ready! Build an amazing chatbot!

The last step is to add this domain to your hosts using Nginx or Apache, I'll leave that up to you but I have my local chatbot site configured as helloworldchatbot.app for
reference in this tutorial. That's it! You now have BotMan installed with Laravel. Let's start developing our chat bot.

Developing locally with BotMan Studio

BotMan Studio comes with a /botman/tinker route which is a simple VueJS based view that allows you to communicate with your ChatBot.
Navigate to your app and go to the route above so for me that's http://helloworldbot.app/botman/tinker

Once there, you will see the following:

BotMan Tinker Route View

Now that we have BotMan installed, let's add our first command! So a core concept of BotMan is the aspect of hearing messages. BotMan will "listen" for
certain commands and this can be setup by you in order to trigger certain events with certain bot commands.

Editing app/Http/Controllers/BotManController - let's add some logic to do just that.

Edit the handle function in the BotManController to be as follows:

{% highlight php startinline %}
<?php
/**
 * Place your BotMan logic here.
 */
public function handle()
{
   $botman = app('botman');

   // our first BotMan command
   $botman->hears('hello', function ($bot) {
      $bot->reply("Hello, I'm Hello World bot!");
   });

    $botman->listen();
}
{% endhighlight %}

The hears function itself is quite simple, it uses a string to indicate what to listen for and then a Closure that indicates what functionality to execute.
And that's it, that's your first command. Now navigate to the tinker route as described before and type "hello" and you should see the following output:

BotMan Hello World

That's kind of boring though isn't it? It would be cool if our chat bot could greet us by name. This is possible and is enabled by using command parameters.

Command parameters are defined by using the hears function and we define the command parameters by enclosing parameters in curly braces {}. Now let's get this bot to say hello! Before adding this to our code. Let's just analyse the code first:

  {% highlight php %}
  <?php
  $botman->hears("hello I'm {name}", function ($bot, $name) {
      $bot->reply("Hello, $name. I'm Hello World bot");
  });
  {% endhighlight %}

The code is obvious, we are still utilizing the hears function however our string now contains a command parameter as denoted by the "{name}".
We then pass that variable to our Closure and then simply tell the $bot to reply as before. BotMan is quite an expressive library as you can see
and aims to be as readable and obvious as possible.

Now that we have a bit of an idea as to how command parameters work, let's edit our handle function. Update it to be as follows:

 {% highlight php %}
 <?php
 /**
  * Place your BotMan logic here.
  */
 public function handle()
 {
     $botman = app('botman');

     // our first BotMan command
     $botman->hears('hello', function ($bot) {
         $bot->reply("Hello, I'm Hello World bot!");
     });


     $botman->hears("hello I'm {name}", function ($bot, $name) {
         $bot->reply("Hello, $name. I'm Hello World bot");
     });


     $botman->listen();
 }
 {% endhighlight %}

If you now navigate to the tinker route, and enter "hello I'm X" (where X is your name, silly) then you will get the following output:

BotMan Hello Name

Refactoring our approach

This is going to get a bit out of hand, imagine our bot is going to listen for a couple hundred keywords
then our approach is going to leave us with one huge handle function. Let's boyscout this as we write it and clean up our code.

Our approach will be to decouple the Closures into a controller (or multiple if you wish) and then call those functions instead. This gives us peace
of mind as it prevents our code from becoming spaghetti code and also allows us to easily add or remove the bot commands/functionality very easily.

Create a new folder in your App\Http\Controllers directory called "Listen" and then create a controller called HelloBotCommandsController. I have done so and simply moved our Closures into their own functions, do note that the namespace is very important here.

{% highlight php %}
<?php

namespace App\Http\Controllers\Listen;

use App\Http\Controllers\Controller;

class HelloBotCommandsController extends Controller
{
    /**
     * Handle when user says "hello"
     * @param $bot
     */
    public function handleSayHello($bot)
    {
        $bot->reply("Hello, I'm Hello World bot!");
    }

    /**
     * Handle when user says "hello, I'm {name}"
     * @param $bot
     * @param $name
     */
    public function handleSayHelloWithName($bot, $name)
    {
        $bot->reply("Hello, $name. I'm Hello World bot");
    }
}
{% endhighlight %}

Now that we have our controller to handle our bot commands, let's update the handle functionality in app/Http/BotManController like so:

  {% highlight php %}
  <?php
  /**
     * Place your BotMan logic here.
     */
    public function handle()
    {
        $botman = app('botman');

        $botman->hears('hello', 'App\Http\Controllers\Listen\HelloBotCommands@handleSayHello');
        $botman->hears("hello I'm {name}", 'App\Http\Controllers\Listen\HelloBotCommands@handleSayHelloWithName');

        $botman->listen();
    }
    {% endhighlight %}

Wrapping Up

That's it, you now have BotMan setup and have your first simple Hello World chatbot. If everything worked out correctly, you should be able to reproduce the below results (on the tinker route):

BotMan Hello World Chatbot Output

We will be continuing this in the next part where we will
look at integrating BotMan with Slack and handling conversations between the Bot and User rather than simple single-message replies.

Let me know if you have any questions in the comments below.

You can find the code for this blog post on github

Happy coding!