Description

PhpBotFramework a lightweight framework for Telegram Bot API. Designed to be fast and easy to use, it provides all the features a user need. Take control of your bot using the command-handler system or the update type based function.

Example

A quick example, the bot will send "Hello" every time the user click "/start":

<?php

// Include the framework
require './vendor/autoload.php';

// Create the bot
$bot = new DanySpin97\PhpBotFramework\Bot("token");

// Add a command that will be triggered every time the user click /start
$bot->addMessageCommand("start",
    function($bot, $message) {
        $bot->sendMessage("Hello");
    }
);

// Receive update from telegram using getUpdates
$bot->getUpdatesLocal();

Features

Designed to be the fast and easy to use
Support for getUpdates and webhooks
Support for the most important API methods
Command-handle system
Update type based processing
Easy inline keyboard creation
Inline query results handler
Sql database support
Redis support
Support for multilanguage bot
Support for bot state
Highly documented

Requirements

Php 7.0 or greater
php-mbstring
Composer (to install the framework)
SSL certificate (required by webhook)
Web server (required by webhook)

Installation

In your project folder:

composer require danyspin97/php-bot-framework
composer install --no-dev

Web-server

To use webhook for the bot, a web server and a SSL certificate are required. Install one using your package manager (nginx or caddy reccomended). To get a SSL certificate you can user Let's Encrypt.

Usage

Add the scripting by adding command (addMessageCommand()) or by creating a class that inherits Bot. Each api call will have $chat_id set to the current user, use setChatID($chat_id) to change it.

getUpdates

The bot ask for updates to telegram server. If you want to use getUpdates method to receive updates from telegram, add one of these function at the end of your bot:

getUpdatesLocal()
getUpdatesDatabase()
getUpdatesRedis()

The bot will process updates in a row, and will call processUpdate() for each. getUpdates handling is single-threaded so there will be only one object that will process updates, so the connection will be opened at the creation and used for the entire life of the bot.

Webhook

A web server will create an instance of the bot for every update received. If you want to use webhook call processWebhookUpdate() at the end of your bot. The bot will get data from php://input and process it using processUpdate(). Each instance of the bot will open its connection.

Commands

Script how the bot will answer to messages containing commands (like /start).

$bot->addMessageCommand("/start", function($bot, $message) {
        $bot->sendMessage("I am your personal bot, try /help command");
});

$help_function = function($bot, $message) {
    $bot->sendMessage("This is the help message")
};

$bot->addMessageCommand("/help", $help_function);

Inherit Bot Class

Create a new class that inherits Bot to handle all updates.

EchoBot.php

class EchoBot extends DanySpin97\PhpBotFramework\Bot {
    protected function processMessage(&$message) {
        $this->sendMessage($this->getText());
    }
}

main.php

$bot = new EchoBot("token");
$bot->processWebhookUpdate();

Override these method to make your bot handle each update type:

processMessage(&$message)
processCallbackQuery(&$callback_query)
processInlineQuery(&$inline_query)
processChosenInlineResult(&$chosen_inline_result)
processEditedMessage(&$edited_message)

InlineKeyboard Usage

How to use the InlineKeyboard class:

// Create the bot
$bot = new DanySpin97\PhpBotFramework\Bot("token");

// Create the inline keyboard object that will handle buttons
$bot->inline_keyboard = new DanySpin97\PhpBotFramework\InlineKeyboard();

$command_function = function($bot, $message) {
        // Add a button to the inline keyboard
        $bot->inline_keyboard->addLevelButtons([
             // with written "Click me!"
             'text' => 'Click me!',
             // and that open the telegram site, if pressed
             'url' => 'telegram.me'
             ]);
        // Then send a message, with our keyboard in the parameter $reply_markup of sendMessage
        $bot->sendMessage("This is a test message", $bot->inline_keyboard->get());
        }

// Add the command
$bot->addMessageCommand("start", $command_function);

Sql Database

The sql database is used to save offset from getUpdates and to save user language. To connect a sql database to the bot, a pdo connection is required. Here is a simple pdo connection that is passed to the bot:

$bot->pdo = new PDO('mysql:host=localhost;dbname=test', $user, $pass);

Redis Database

Redis is used to save offset from getUpdates, to store language (both as cache and persistent) and to save bot state. To connect redis with the bot, craete a redis object.

$bot->redis = new Redis();

Multilanguage Bot

This framework offers method to develop a multi language bot. Here's an example:

$bot->localization = [ 'en' =>
                              [ 'Greetings_Msg' => 'Hello'],
                       'it' =>
                              [ 'Greetings_Msg' => 'Ciao']];

$start_function = function($bot, $message) {
        $bot->sendMessage($this->localization[
                $bot->getLanguageDatabase()]['Greetings_Msg'])
};

$bot->addMessageCommand("start", $start_function);

The bot will get the language from the database, then the bot will send the message localizated for the user.

Multilanguage [See here for more]

Source

The source is hosted on github and can be found here.

Bot using this framework

Authors

This framework is developed and manteined by Danilo Spinella.

License

PhpBotFramework is released under GNU Lesser General Public License. You may copy, distribute and modify the software provided that modifications are described and licensed for free under LGPL-3. Derivatives works (including modifications) can only be redistributed under LGPL-3, but applications that use the wrapper don't have to be.