PhpBotFramework\Core\CoreBot

Complexity

Total Complexity

20

Size/Duplication

Total Lines	233
Duplicated Lines	0 %

Coupling/Cohesion

Components	2
Dependencies	8

Test Coverage

Coverage

82.14%

Importance

Changes

0

10 Methods

Rating	Name	Duplication	Size	Complexity
A	__construct()	0	20	3
A	getChatID()	0	4	1
A	setChatID()	0	4	1
A	getBotID()	0	10	3
A	apiRequest()	0	4	1
B	processRequest()	0	23	4
A	checkCurrentFile()	0	9	2
A	execRequest()	0	6	1
A	execMultipartRequest()	0	12	1
A	checkRequestError()	0	18	3

<?php

/*
 * This file is part of the PhpBotFramework.
 *
 * PhpBotFramework is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation, version 3.
 *
 * PhpBotFramework is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program. If not, see <http://www.gnu.org/licenses/>.
 */

namespace PhpBotFramework\Core;

use PhpBotFramework\Exceptions\BotException;

use PhpBotFramework\Entities\File as TelegramFile;

use PhpBotFramework\Entities\InlineKeyboard;

/**
 * \mainpage
 * \section Description
 * PhpBotFramework is a lightweight framework for [Telegram Bot API](https://core.telegram.org/bots/api).
 * Designed to be fast and easy to use, it provides all the features a user need in order to start
 * developing Telegram bots..
 *
 * \section Installation
 * You can install PhpBotFramework using **Composer**.
 *
 * Go to your project's folder and type:
 *
 *     composer require danyspin97/php-bot-framework
 *     composer install --no-dev
 *
 * \section Usage
 * You can start working on your bot creating a new instance of Bot or by creating a
 * class that inherits from it.
 *
 * Each API call will have <code>$_chat_id</code> set to the current user:
 * you can use CoreBot::setChatID() to change it.
 *
 * Below an example bot you can look to:
 *
 *
 *     <?php
 *
 *     // Include the framework
 *     require './vendor/autoload.php';
 *
 *     // Create the bot
 *     $bot = new PhpBotFramework\Bot("token");
 *
 *     // Create a command that will be triggered every time the user send /start
 *     $start_command = new PhpBotFramework\Commands\MessageCommand("start", function($bot, $message) {
 *         $bot->sendMessage("Hello, folks!");
 *     });
 *
 *     $bot->addCommand($start_command);
 *
 *     // Shortcut for add message commands.
 *     $bot->addMessageCommand('about', function($bot, $message) {
 *         $bot->sendMessage('Powered by PhpBotFramework');
 *     });
 *
 *     // Receive updates from Telegram using getUpdates
 *     $bot->getUpdatesLocal();
 *
 * \subsection Bot-Intherited Inheriting by Bot class
 *
 *     <?php
 *
 *     // Include the framework
 *     require './vendor/autoload.php';
 *
 *     // Create the class that will extends Bot class
 *     class EchoBot extends PhpBotFramework\Bot {
 *
 *         // Add the function for processing messages
 *         protected function processMessage($message) {
 *
 *             // Answer each message with the text received
 *             $this->sendMessage($message['text']);
 *         }
 *     }
 *
 *     $bot = new EchoBot("token");
 *
 *     // Process updates using webhook
 *     $bot->processWebhookUpdate();
 *
 * Override these method to make your bot handle each update type:
 * - Bot::processMessage($message)
 * - Bot::processCallbackQuery($callback_query)
 * - Bot::processInlineQuery($inline_query)
 * - Bot::processChosenInlineResult($_chosen_inline_result)
 * - Bot::processEditedMessage($edited_message)
 * - Bot::processChannelPost($post)
 * - Bot::processEditedChannelPost($edited_post)
 *
 * \section Features
 * - Modular: take only what you need
 * - Flexible HTTP requests with [Guzzle](https://github.com/guzzle/guzzle)
 * - Designed to be fast and easy to use
 * - Support for local updates and webhooks
 * - Support for the most important API methods
 * - Command-handle system for messages and callback queries
 * - Update type based processing
 * - Easy **inline keyboard** creation
 * - Inline query results handler
 * - Database support and facilities
 * - Redis support
 * - Support for multilanguage bots
 * - Support for bot states
 * - Highly-documented
 *
 * \section Requirements
 * - PHP >= 7.0
 * - php-mbstring
 * - Composer (to install the framework)
 * - Web server: *required for webhook* (we recommend [nginx](http://nginx.org/))
 * - SSL certificate: *required for webhook* (follow [these steps](https://devcenter.heroku.com/articles/ssl-certificate-self) to make a self-signed certificate or use [Let's Encrypt](https://letsencrypt.org/))
 *
 * \section GetUpdates-section Getting updates
 * Everytime a user interacts with the bot, an `update` is generated by Telegram's servers.
 *
 * There are two ways of receiving this updates:
 * - use [Telegram Bot API's `getUpdates`](https://core.telegram.org/bots/api#getupdates) method
 * - use webhooks (it's covered in the next section)
 *
 * If you want to use `getUpdates` in order to receive updates,
 * add one of these functions at the end of your bot:
 * - Bot::getUpdatesLocal()
 * - Bot::getUpdatesDatabase()
 * - Bot::getUpdatesRedis()
 *
 * The bot will process updates one a time and will call Bot::processUpdate() for each.
 *
 * The connection will be opened at the creation and used for the entire life of the bot.
 *
 * \section Webhook-section Webhook
 * An alternative way to receive updates is using **webhooks**.
 *
 * Everytime a user interacts with the bot, Telegram servers send the update through
 * a POST request to a URL chose by you.
 *
 * A web server will create an instance of the bot for every update received.
 *
 * If you want to use webhook: call Bot::processWebhookUpdate() at the end of your bot.
 *
 * The bot will get data from <code>php://input</code> and process it using Bot::processUpdate().
 * Each instance of the bot will open its connection.
 *
 * \subsection Setwebhooks-subsection Set webhook
 * You can set a URL for your bot's webhook using CoreBot::setWebhook():
 *
 *     //...
 *     $bot->setWebhook([ 'url' => 'https://example.com/mybotSECRETPATH' ])
 *
 * You can learn more about `setWebhook` and webhooks [here](https://core.telegram.org/bots/api#setwebhook).
 *
 * \section Message-commands Bot's commands
 * One of the most important tasks during a Telegram bot's development is register
 * the commands the bot will respond to.
 *
 * PhpBotFrameworks makes it easy:
 *
 *     $start_message_command = new PhpBotFramework\Commands\MessageCommand("start", function($bot, $message) {
 *         $bot->sendMessage("I am your personal bot, try /help command");
 *     });
 *
 *     $bot->addCommand($start_message_command);
 *
 *     $help_closure = function($bot, $message) {
 *         $bot->sendMessage("This is the help message")
 *     };
 *
 *     $help_message_command = new PhpBotFramework\Commands\MessageCommand("/help", $help_function);
 *
 *     $bot->addCommand($help_message_command);
 *
 * The message commands are so used that we eventually decided to add a dedicated method:
 *
 *     $bot->addMessageCommand('start', function($bot, $message) {
 *         $bot->sendMessage('I am your personal bot, try /help command');
 *     });
 *
 * \subsection Bot-commands-regex Check commands using regex
 *
 * You can also use **regular expressions** to check for the given command:
 *
 *     $regex_command = new PhpBotFramework\Commands\MessageRegexCommand("number\d", $help_function);
 *
 * The closure will be called when the user send a command that match the given regex,
 * in this example: both <code>/number1</code> or <code>/number135</code>.
 *
 * \subsection Callback-commands Callback commands
 * You can also check for a callback query containing a particular string as data:
 *
 *     $callback_command = new PhpBotFramework\Commands\CallbackCommand("back", function($bot, $callback_query) {
 *         $bot->editMessageText($callback_query['message']['message_id'], "You pressed back");
 *     });
 *
 * You should absolutely check Bot::addCommand() for learning more.
 *
 * \subsection Add multiple commands at once.
 * If you've to add a lot of commands you can add all of them at once:
 *
 *     $callback_command = new PhpBotFramework\Commands\CallbackCommand("back", function($bot, $callback_query) {
 *         $bot->editMessageText($callback_query['message']['message_id'], "You pressed back");
 *     });
 *
 *     $callback_command_2 = new PhpBotFramework\Commands\CallbackCommand("delete", function($bot, $callback_query) {
 *         $bot->editMessageText($callback_query['message']['message_id'], "You pressed delete");
 *     });
 *
 *     $bot->addCommands($callback_command, $callback_command_2);
 *
 * \section InlineKeyboard-Usage Inline keyboards
 *
 * Telegram implements something called [inline keyboards](https://core.telegram.org/bots#inline-keyboards-and-on-the-fly-updating) which allows users to send commands to a
 * bot tapping on buttons instead of typing text.
 *
 * PhpBotFrameworks supports **inline keyboard** and you can easily integrate it with your bot:
 *
 *     $bot = new PhpBotFramework\Bot("token");
 *
 *     $command = ("start", function($bot, $message) {
 *         // Add a button to the inline keyboard with written 'Click me!' and
 *         // that open the Telegram site if pressed.
 *         $bot->inline_keyboard->addLevelButtons([
 *             'text' => 'Click me!',
 *             '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->addCommand($command);
 *
 * \section Sql-Database Database
 * A database is required in order to save offsets (if you use local updates)
 * and save user's language.
 *
 * We implemented a simpler way to connect to a database which is based on PDO:
 *
 *     $bot->database->connect([
 *         'adapter' => 'pgsql',
 *         'username' => 'sysuser',
 *         'password' => 'myshinypassword',
 *         'dbname' => 'my_shiny_bot'
 *     ]);
 *
 * This method will istantiate a new PDO connection and a new PDO object you can
 * access through `$bot->getPdo()`.
 *
 * If no adapter and host are specified: `mysql` and `localhost` are assigned.
 *
 * \subsection Redis-database Redis
 * **Redis** is used across PhpBotFramework in order to save offsets for local updates,
 * to store user's language (both as cache and persistent) and save bot states.
 *
 * Redis and the main database are complementary so you need to set both.
 *
 * All you need to do, in order to enable Redis for your bot, is create a new Redis object:
 *
 *     $bot->redis = new Redis();
 *
 * \section Multilanguage-section Multi-language Bot
 * This framework offers methods and facilities for develop a multi-language bot.
 *
 * All you need to do is create a `localization` folder in your project's root folder
 * and store there the JSON files with bot's messages:
 *
 * <code>localization/en.json</code>:
 *
 *     { "Welcome_Message": "Hello, folks!" }
 *
 * <code>localization/it.json</code>:
 *
 *     { "Welcome_Message": "Ciao, gente!" }
 *
 * <code>main.php</code>:
 *
 *     // ...
 *
 *     $start_command = PhpBotFramework\Commands\MessageCommand("start", function($bot, $message) {
 *         $bot->sendMessage($bot->local->getStr('Greetings_Msg'));
 *     });
 *
 *     $bot->addCommand($start_command);
 *
 * So you can have a wonderful (multi-language) bot with a small effort.
 *
 * \section Source
 * **PhpBotFramework** is an open-source project so everyone can contribute to it.
 *
 * It's currently hosted on GitHub [here](https://github.com/DanySpin97/PhpBotFramework).
 *
 * \section Createdwith-section Made with PhpBotFramework
 *
 * - [MyAddressBookBot](https://github.com/DanySpin97/MyAddressBookBot): [Try it on Telegram](https://telegram.me/myaddressbookbot)
 * - [Giveaways_Bot](https://github.com/DanySpin97/GiveawaysBot): [Try it on Telegram](https://telegram.me/giveaways_bot)
 *
 * \section Testing
 * PhpBotFramework comes with a test suite you can run using **PHPUnit**.
 *
 * You need a valid bot token and chat ID in order to run tests:
 *
 *      export BOT_TOKEN=YOURBOTTOKEN
 *      export CHAT_ID=YOURCHATID
 *
 * After you've set the necessary, you can run the test suite typing:
 *
 *      phpunit
 *
 * \section Authors
 * This framework is developed and mantained by [Danilo Spinella](https://github.com/DanySpin97) and [Dom Corvasce](https://github.com/domcorvasce).
 *
 * \section License
 * PhpBotFramework is released under [GNU Lesser General Public License v3](https://www.gnu.org/licenses/lgpl-3.0.en.html).
 *
 * 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.
 *
 */

/**
 * \class CoreBot
 * \brief Core of the framework
 * \details Contains data used by the bot to works, curl request handling, and all api methods (sendMessage, editMessageText, etc).
 */
class CoreBot
{
    use Updates,
        Send,
        Edit,
        Inline,
        Chat;

    /** @internal
      * \brief Chat_id of the user that interacted with the bot. */
    protected $_chat_id;

    /** @internal
      * \brief Bot id. */
    protected $_bot_id;

    /** @internal
      * \brief API endpoint (containing $token). */
    protected $_api_url;

    /** @internal
      * \brief Implements interface for execute HTTP requests. */
    public $_http;

    /** @internal
      * \brief Object of class PhpBotFramework\Entities\File that contain a path or resource to a file that has to be sent using Telegram API Methods. */
    protected $_file;

    /** \@internal
      * brief Contains parameters of the next request. */
    protected $parameters;

    /**
     * \@internal
     * brief Initialize a new bot.
     * \details Initialize a new bot passing its token.
     * @param $token Bot's token given by @botfather.
     */
    public function __construct(string $token)
    {
        // Check if token is valid
        if (is_numeric($token) || $token === '') {
            throw new BotException('Token is not valid or empty');
        }

        $this->_api_url = "https://api.telegram.org/bot$token/";

        // Init connection and config it
        $this->_http = new \GuzzleHttp\Client([
            'base_uri' => $this->_api_url,
            'connect_timeout' => 5,
            'verify' => false,
            'timeout' => 60,
            'http_errors' => false
        ]);

        $this->_file = new TelegramFile();
    }

    /**
     * \addtogroup Bot Bot
     * @{
     */

    /**
     * \brief Get chat ID of the current user.
     * @return int Chat ID of the user.
     */
    public function getChatID()
    {
        return $this->_chat_id;
    }

    /**
     * \brief Set current chat ID.
     * \details Change the chat ID on which the bot acts.
     * @param $chat_id The new chat ID to set.
     */
    public function setChatID($chat_id)
    {
        $this->_chat_id = $chat_id;
    }

    /**
     * \brief Get bot ID using `getMe` method.
     * @return int Bot id, 0 on errors.
     */
    public function getBotID() : int
    {
        // If it is not valid
        if (!isset($this->_bot_id) || $this->_bot_id == 0) {
            // get it again
            $this->_bot_id = ($this->getMe())['id'];
        }

        return $this->_bot_id ?? 0;
    }

    /** @} */

    /**
     * \addtogroup Api Api Methods
     * \brief Implementations for Telegram Bot API's methods.
     * @{
     */

    /**
     * \brief Execute any API request using this method.
     * \details Use this method for custom api calls using this syntax:
     *
     *     $param = [
     *             'chat_id' => $_chat_id,
     *             'text' => 'Hello!'
     *     ];
     *     apiRequest("sendMessage", $param);
     *
     * @param string $method The method to call.
     * @param array $parameters Parameters to add.
     * @return mixed Depends on api method.
     */
    public function apiRequest(string $method, array $parameters)
    {
        return $this->execRequest($method . '?' . http_build_query($parameters));
    }

    /** @} */

    /**
     * \@internal
     * brief Process an API method by taking method and parameter.
     * \details optionally create a object of $class class name with the response as constructor param.
     * @param string $method Method to call.
     * @param array $param Parameter for the method.

There is no parameter named $param. Was it maybe removed?

     * @param string $class Class name of the object to create using response.
     * @return mixed Response or object of $class class name.
     */
    protected function processRequest(string $method, string $class = '', $file = false)
    {
        $url = "$method?" . http_build_query($this->parameters);

        // If there is a file to upload
        if ($file === false) {
            $response = $this->execRequest($url);
        } else {
            $response = $this->execMultipartRequest($url);
        }

        if ($response === false) {
            return false;
        }

        if ($class !== '') {
            $object_class = "PhpBotFramework\Entities\\$class";

            return new $object_class($response);
        }

        return $response;
    }

    /**
     * @internal
     * \brief Check if the current file is local or not.
     * \details If the file file is local, then it has to be uploaded using multipart. If not, then it is a url/file_id so it has to be added in request parameters as a string.
     * @return PhpBotFramework\Entities\File|false The file that will be sent using multipart, false otherwise.
     */
    protected function checkCurrentFile()
    {
        if (!$this->_file->isLocal()) {
            $this->parameters[$this->_file->getFormatName()] = $this->_file->getString();
            return false;
        }

        return $this->_file;
    }


    /**
     * @internal
     * \brief Core function to execute HTTP request.
     * @param $url The request's URL.
     * @return Array|false Url response decoded from JSON, false on error.
     */
    protected function execRequest(string $url)
    {
        $response = $this->_http->request('POST', $url);

        return $this->checkRequestError($response);
    }

    /**
     * @internal
     * \brief Core function to execute HTTP request uploading a file.
     * \details Using an object of type PhpBotFramework\Entities\File contained in $_file and Guzzle multipart request option, it uploads the file along with api method requested.
     * @param $url The request's URL.
     * @return Array|false Url response decoded from JSON, false on error.
     */
    protected function execMultipartRequest(string $url)
    {
        $response = $this->_http->request('POST', $url, [
            'multipart' => [
                [
                    'name' => $this->_file->getFormatName(),
                    'contents' => $this->_file->getResource()
                ]
            ]]);

        return $this->checkRequestError($response);
    }

    public function checkRequestError($response)
    {
        $http_code = $response->getStatusCode();

        if ($http_code === 200) {
            $response = json_decode($response->getBody(), true);

            return $response['result'];
        } elseif ($http_code >= 500) {
            // do not wat to DDOS server if something goes wrong
            sleep(10);
            return false;
        } else {
            $response = json_decode($response->getBody(), true);
            error_log("Request has failed with error {$response['error_code']}: {$response['description']}\n");
            return false;
        }
    }

    /** @} */

    /** @} */
}