Merge pull request #1168 from noplanman/1161-custom-bot-api-server

Allow custom Bot API server to be used

Author: noplanman

CHANGELOG.md

@@ -7,6 +7,7 @@ Exclamation symbols (:exclamation:) note something of importance e.g. breaking c
 ### Notes
 - [:ledger: View file changes][Unreleased]
 ### Added
+- Define a custom Bot API server and file download URI.
 ### Changed
 - Improved error messages for empty input.
 - Log update when processing it, not when fetching input.

README.md

@@ -27,6 +27,7 @@ A Telegram Bot based on the official [Telegram Bot API]
     - [Create your first bot](#create-your-first-bot)
     - [Require this package with Composer](#require-this-package-with-composer)
     - [Choose how to retrieve Telegram updates](#choose-how-to-retrieve-telegram-updates)
+- [Using a custom Bot API server](#using-a-custom-bot-api-server)
 - [Webhook installation](#webhook-installation)
     - [Self Signed Certificate](#self-signed-certificate)
     - [Unset Webhook](#unset-webhook)
@@ -200,6 +201,23 @@ The bot can handle updates with [**Webhook**](#webhook-installation) or [**getUp
 | Host with https | Required | Not required |
 | MySQL | Not required | ([Not](#getupdates-without-database)) Required  |
 
+## Using a custom Bot API server
+
+**For advanced users only!**
+
+As from Telegram Bot API 5.0, users can [run their own Bot API server] to handle updates.
+This means, that the PHP Telegram Bot needs to be configured to serve that custom URI.
+Additionally, you can define the URI where uploaded files to the bot can be downloaded (note the `{API_KEY}` placeholder).
+
+```php
+Longman\TelegramBot\Request::setCustomBotApiUri(
+    $api_base_uri          = 'https://your-bot-api-server', // Default: https://api.telegram.org
+    $api_base_download_uri = '/path/to/files/{API_KEY}'     // Default: /file/bot{API_KEY}
+);
+```
+
+**Note:** If you are running your bot in `--local` mode, you won't need the `Request::downloadFile()` method, since you can then access your files directly from the absolute path returned by `Request::getFile()`.
+
 ## Webhook installation
 
 Note: For a more detailed explanation, head over to the [example-bot repository] and follow the instructions there.
@@ -657,6 +675,7 @@ Credit list in [CREDITS](CREDITS)
 
 [Telegram Bot API]: https://core.telegram.org/bots/api "Telegram Bot API"
 [Composer]: https://getcomposer.org/ "Composer"
+[run their own Bot API server]: https://core.telegram.org/bots/api#using-a-local-bot-api-server "Using a Local Bot API Server"
 [example-bot repository]: https://github.com/php-telegram-bot/example-bot "Example Bot repository"
 [api-setwebhook]: https://core.telegram.org/bots/api#setwebhook "Webhook on Telegram Bot API"
 [set.php]: https://github.com/php-telegram-bot/example-bot/blob/master/set.php "example set.php"

src/Request.php

@@ -116,6 +116,13 @@ class Request
      */
     private static $api_base_uri = 'https://api.telegram.org';
 
+    /**
+     * URI of the Telegram API for downloading files (relative to $api_base_url or absolute)
+     *
+     * @var string
+     */
+    private static $api_base_download_uri = '/file/bot{API_KEY}';
+
     /**
      * Guzzle Client object
      *
@@ -292,6 +299,20 @@ public static function setClient(ClientInterface $client): void
         self::$client = $client;
     }
 
+    /**
+     * Set a custom Bot API URL
+     *
+     * @param string $api_base_uri
+     * @param string $api_base_download_uri
+     */
+    public static function setCustomBotApiUri(string $api_base_uri, string $api_base_download_uri = ''): void
+    {
+        self::$api_base_uri = $api_base_uri;
+        if ($api_base_download_uri !== '') {
+            self::$api_base_download_uri = $api_base_download_uri;
+        }
+    }
+
     /**
      * Get input from custom input or stdin and return it
      *
@@ -532,8 +553,9 @@ public static function downloadFile(File $file): bool
         $debug_handle = TelegramLog::getDebugLogTempStream();
 
         try {
+            $base_download_uri = str_replace('{API_KEY}', self::$telegram->getApiKey(), self::$api_base_download_uri);
             self::$client->get(
-                '/file/bot' . self::$telegram->getApiKey() . '/' . $tg_file_path,
+                "{$base_download_uri}/{$tg_file_path}",
                 ['debug' => $debug_handle, 'sink' => $file_path]
             );