Bot Chassis
WARNING: Currently in ALPHA state due to:
- quickstart not tested and controller.md not finished
- the telegram-bot-sdk currently used is no stable version
- test coverage is low (but slowly growing)
- integration options for plain php are lacking
- no argument validation of Chassis API, (*1)
What?
Adds a fully featured layer upon the basic telegram API (telegram-bot-sdk) to drastically speed up telegram bot development, (*2)
Why?
The telegram-bot-sdk offers a stable API layer for bot development. However, for a fully featured bot many aspects are missing. Instead of jumping into defining the behaviour of the bot, you first need some routing system to handle arbitrary updates, a system to keep track of user conversations and persist associated data, and so on. This package aims to implement this middle layer and enables you to go straight for the fun part!, (*3)
Feature Overview
-
Builds upon telegram-bot-sdk and makes all features easily accessible, (*4)
-
Use controller to easily handle any incoming updates. E.g, (*5)
- Process commands (
/text)
- Process any (other) text messages
- Process inline and callback queries
- React to Events like users joining and leaving chat etc.
-
Use simple but powerful configuration to wire up and chain Controller, (*6)
-
Integrate with Laravel (and Redis as Backend) out of the box (see below for upcoming options), (*7)
-
Out-of-the-box persistent storage of metadata, (*8)
- per conversation (linked to user and chat), message (for callback_queries), chat or user
- Support for conversations (chain of messages) and helper to control message flow
- Attach handler to your CallbackQueries just as easily
Documentation
See below for a quickstart tutorial, (*9)
Installation methods, configuration options, framework integration and telegram-bot-sdk integration., (*10)
Controller (coming soon)
Routing of updates to Controller, Controller features, persistent MetaData storage, (*11)
API (coming soon)
A bot can only do as much as is defined in the official telegram bot API., (*12)
bot-chassis is build upon telegram-bot-sdk with all features supported. Check the Migration Guide if you are coming from telegram-bot-sdk., (*13)
Feedback, Questions, Contributions
For all these you can use the issue tracker., (*14)
You could also find me and other bot developers at Slack PHP Chat
(Direct message irazasyed for access to #telegram-bot-sdk), (*15)
Pull requests are most appreciated if they use PSR-2 Coding Standards, have tests and can be pulled from a feature-branch., (*16)
Quickstart
This tutorial uses Laravel and Redis and introduces the basic features Controller and MetaData., (*17)
For more alternatives check the integration guide [Configuration]., (*18)
Installation
Install PHP7, Laravel and Redis. Configure Laravel to use your database and redis instance., (*19)
Tell composer to use the telegram-bot-sdk with dev stability (needed until we can use a stable version):, (*20)
composer require irazasyed/telegram-bot-sdk:@dev
Add bot-chassis to the composer.json:, (*21)
composer require sloothword/bot-chassis
Add the LaravelServiceProvider in the app.php:, (*22)
'providers' => [
...
Chassis\Laravel\ChassisServiceProvider::class,
Publish the configuration (and migrations), (*23)
artisan vendor:publish
Open config/chassis.php and insert your bot credentials., (*24)
Test Run
Send a command to the bot (commands /echo, /delayed, /double, see Chassis/Controller/EchoController.php), then call artisan chassis:handle to process it., (*25)
Tutorial Bot
This tutorial bot will have three functions:
- The bot adds every integer messages in the chat.
- /reset sets the counter back to 0
- /set sets the counter to the next sent integer, (*26)
Controller
Create a new Controller under your application namespace and structure., (*27)
<?php
namespace App\Controller;
use Chassis\Controller\Controller;
class CountController extends Controller
{
public function add(){
// Add sent number to counter
}
public function reset(){
// Reset the counter
}
public function set(){
// Set the counter to the next integer message
}
}
and add it to the controller list in chassis.php (and remove the others):, (*28)
'bots' => [
'mybot' => [
'username' => 'BOT-USERNAME',
'token' => env('TELEGRAM_BOT_TOKEN', 'BOT-TOKEN'),
'shared' => [],
'controllers' => [
['text', App\Controller\CountController::class, 'add'],
['/reset', App\Controller\CountController::class, 'reset'],
['/set', App\Controller\CountController::class, 'set']
],
],
],
Now everytime you send the /reset command to the Bot the reset()method of CountControlleris called. Everytime we send text to the bot (which is no command) the add() method is called., (*29)
Learn to count
The MetaData you get by calling $this->getConversationData() (shortcut for $this->getMetaData($this->getUpdate()) in any Controller is persisted by the Chassis framework and linked to the current conversation. Using this here means that each user and chat has its own counter., (*30)
We could also use the MetaData object linked to the user ($this->getMetaData($this->getUser())) to get each user a single counter across all chats. With $this->getMetaData($this->getChat()) all users of a chat could count together., (*31)
class CountController extends Controller
{
public function add(){
$value = intval($this->getText());
$conversationData = $this->getConversationData();
$counter = $conversationData->get('count', 0);
$conversationData['count'] = $counter + $value;
$this->replyWithMessage(['text' => 'New value: ' .$conversationData['count']]);
}
public function reset(){
$this->getConversationData()->forget('count');
$this->replyWithMessage(['text' => 'Reset counter']);
}
}
Notes:
- You do not need to be concerned about saving back the changed MetaData as it will be done automatically.
- MetaData extends Illuminate/Support/Collection (see get(), has() and forget() methods).
- $this->getText() is a shortcut for $this->getUpdate()->getMessage()->getText()
- Controller uses the Telegram\Bot\Answers\Answerable trait, so you can use all the reply* methods, (*32)
For the /set command we need to do three things:
- Instruct the user to message the new count
- Define which controller method should handle the response
- In that method set the counter to the message text, (*33)
public function set(){
$this->replyWithMessage(['text' => 'Insert new value:']);
$this->getConversationData()->nextConversationStep(self::class, 'saveCounter');
}
public function saveCounter(){
$value = intval($this->getText());
$conversationData = $this->getConversationData();
$conversationData['count'] = $value;
$this->replyWithMessage(['text' => 'Set counter to ' .$value]);
$conversationData->clearConversation();
}
Pay attention to the last line: as we set the next handling method to saveCounter() the bot will always call that same method untill we tell him not to ->clearConversation()., (*34)
Note: This behaviour will change soon., (*35)
Finish
Play around with your finished bot., (*36)
Also try artisan chassis:handle --loop to continously run your bot., (*37)
For more features and detailed information check out the documentation Documentation., (*38)
Wallogit.com
sloothword