Merge pull request #1067 from noplanman/1063_bot_api_4.7

Bot API 4.7

Author: noplanman

CHANGELOG.md

@@ -11,6 +11,7 @@ Exclamation symbols (:exclamation:) note something of importance e.g. breaking c
 - Chain the exception thrown when getting commands from path. (#1030)
 - Support `language_code` in `DB::selectChats()` for filtering the chats selection.
 - Bot API 4.6 (Polls 2.0).
+- Bot API 4.7 (Dice, Sticker Sets, Bot Commands).
 ### Changed
 - Save notes an unescaped JSON, to allow easy DB reading and editing of values. (#1005)
 - `Request::setClient()` now accepts more flexible `ClientInterface`. (#1068)

README.md

@@ -7,7 +7,7 @@
 
 A Telegram Bot based on the official [Telegram Bot API]
 
-[![API Version](https://img.shields.io/badge/Bot%20API-4.6%20%28January%202020%29-32a2da.svg)](https://core.telegram.org/bots/api#december-31-2019)
+[![API Version](https://img.shields.io/badge/Bot%20API-4.7%20%28March%202020%29-32a2da.svg)](https://core.telegram.org/bots/api#december-31-2019)
 [![Join the bot support group on Telegram](https://img.shields.io/badge/telegram-@PHP__Telegram__Bot__Support-64659d.svg)](https://telegram.me/PHP_Telegram_Bot_Support)
 [![Donate](https://img.shields.io/badge/%F0%9F%92%99-Donate%20%2F%20Support%20Us-blue.svg)](#donate)
 
@@ -76,7 +76,7 @@ This Bot aims to provide a platform where one can simply write a bot and have in
 
 The Bot can:
 - Retrieve updates with [webhook](#webhook-installation) and [getUpdates](#getupdates-installation) methods.
-- Supports all types and methods according to Telegram API 4.6 (January 2020).
+- Supports all types and methods according to Telegram API 4.7 (March 2020).
 - Supports supergroups.
 - Handle commands in chat with other bots.
 - Manage Channel from the bot admin interface.
@@ -94,7 +94,7 @@ This code is available on [GitHub](https://github.com/php-telegram-bot/core). Pu
 ### Create your first bot
 
 1. Message [`@BotFather`](https://telegram.me/BotFather) with the following text: `/newbot`
-   
+
    If you don't know how to message by username, click the search field on your Telegram app and type `@BotFather`, where you should be able to initiate a conversation. Be careful not to send it to the wrong contact, because some users have similar usernames to `BotFather`.
 
    ![BotFather initial conversation](https://user-images.githubusercontent.com/9423417/60736229-bc2aeb80-9f45-11e9-8d35-5b53145347bc.png)
@@ -108,7 +108,7 @@ This code is available on [GitHub](https://github.com/php-telegram-bot/core). Pu
 3. Type whatever name you want for your bot.
 
 4. `@BotFather` replies with:
-    
+
     ```
     Good. Now let's choose a username for your bot. It must end in `bot`. Like this, for example: TetrisBot or tetris_bot.
     ```

src/DB.php

@@ -976,7 +976,7 @@ public static function insertMessageRequest(Message $message)
                     `forward_signature`, `forward_sender_name`, `forward_date`,
                     `reply_to_chat`, `reply_to_message`, `edit_date`, `media_group_id`, `author_signature`, `text`, `entities`, `caption_entities`,
                     `audio`, `document`, `animation`, `game`, `photo`, `sticker`, `video`, `voice`, `video_note`, `caption`, `contact`,
-                    `location`, `venue`, `poll`, `new_chat_members`, `left_chat_member`,
+                    `location`, `venue`, `poll`, `dice`, `new_chat_members`, `left_chat_member`,
                     `new_chat_title`, `new_chat_photo`, `delete_chat_photo`, `group_chat_created`,
                     `supergroup_chat_created`, `channel_chat_created`, `migrate_to_chat_id`, `migrate_from_chat_id`,
                     `pinned_message`, `invoice`, `successful_payment`, `connected_website`, `passport_data`, `reply_markup`
@@ -985,7 +985,7 @@ public static function insertMessageRequest(Message $message)
                     :forward_signature, :forward_sender_name, :forward_date,
                     :reply_to_chat, :reply_to_message, :edit_date, :media_group_id, :author_signature, :text, :entities, :caption_entities,
                     :audio, :document, :animation, :game, :photo, :sticker, :video, :voice, :video_note, :caption, :contact,
-                    :location, :venue, :poll, :new_chat_members, :left_chat_member,
+                    :location, :venue, :poll, :dice, :new_chat_members, :left_chat_member,
                     :new_chat_title, :new_chat_photo, :delete_chat_photo, :group_chat_created,
                     :supergroup_chat_created, :channel_chat_created, :migrate_to_chat_id, :migrate_from_chat_id,
                     :pinned_message, :invoice, :successful_payment, :connected_website, :passport_data, :reply_markup
@@ -1041,6 +1041,7 @@ public static function insertMessageRequest(Message $message)
             $sth->bindValue(':location', $message->getLocation());
             $sth->bindValue(':venue', $message->getVenue());
             $sth->bindValue(':poll', $message->getPoll());
+            $sth->bindValue(':dice', $message->getDice());
             $sth->bindValue(':new_chat_members', $new_chat_members_ids);
             $sth->bindValue(':left_chat_member', $left_chat_member_id);
             $sth->bindValue(':new_chat_title', $message->getNewChatTitle());

src/Entities/BotCommand.php

@@ -0,0 +1,27 @@
+<?php
+
+/**
+ * This file is part of the TelegramBot package.
+ *
+ * (c) Avtandil Kikabidze aka LONGMAN <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Longman\TelegramBot\Entities;
+
+/**
+ * Class BotCommand
+ *
+ * This entity represents a bot command.
+ *
+ * @link https://core.telegram.org/bots/api#botcommand
+ *
+ * @method string getCommand()     Text of the command, 1-32 characters. Can contain only lowercase English letters, digits and underscores.
+ * @method string getDescription() Description of the command, 3-256 characters.
+ */
+class BotCommand extends Entity
+{
+
+}

src/Entities/Dice.php

@@ -0,0 +1,26 @@
+<?php
+
+/**
+ * This file is part of the TelegramBot package.
+ *
+ * (c) Avtandil Kikabidze aka LONGMAN <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Longman\TelegramBot\Entities;
+
+/**
+ * Class Dice
+ *
+ * This entity represents a dice with random value from 1 to 6.
+ *
+ * @link https://core.telegram.org/bots/api#dice
+ *
+ * @method int getValue() Value of the dice, 1-6
+ */
+class Dice extends Entity
+{
+
+}

src/Entities/Message.php

@@ -51,6 +51,7 @@
  * @method Location          getLocation()              Optional. Message is a shared location, information about the location
  * @method Venue             getVenue()                 Optional. Message is a venue, information about the venue
  * @method Poll              getPoll()                  Optional. Message is a native poll, information about the poll
+ * @method Dice              getDice()                  Optional. Message is a dice with random value from 1 to 6
  * @method User[]            getNewChatMembers()        Optional. A new member(s) was added to the group, information about them (one of this members may be the bot itself)
  * @method User              getLeftChatMember()        Optional. A member was removed from the group, information about them (this member may be the bot itself)
  * @method string            getNewChatTitle()          Optional. A chat title was changed to this value
@@ -96,6 +97,7 @@ protected function subEntities()
             'location'           => Location::class,
             'venue'              => Venue::class,
             'poll'               => Poll::class,
+            'dice'               => Dice::class,
             'new_chat_members'   => [User::class],
             'left_chat_member'   => User::class,
             'new_chat_photo'     => [PhotoSize::class],

src/Entities/ServerResponse.php

@@ -134,14 +134,15 @@ private function createResultObject(array $result, $bot_username)
      * @param array  $result
      * @param string $bot_username
      *
-     * @return ChatMember[]|GameHighScore[]|Message[]|Update[]
+     * @return BotCommand[]|ChatMember[]|GameHighScore[]|Message[]|Update[]
      */
     private function createResultObjects(array $result, $bot_username)
     {
         $results = [];
         $action  = Request::getCurrentAction();
 
         $result_object_types = [
+            'getMyCommands'         => BotCommand::class,
             'getChatAdministrators' => ChatMember::class,
             'getGameHighScores'     => GameHighScore::class,
             'sendMediaGroup'        => Message::class,

src/Entities/StickerSet.php

@@ -21,6 +21,7 @@
  * @method bool      getIsAnimated()    True, if the sticker set contains animated stickers
  * @method bool      getContainsMasks() True, if the sticker set contains masks
  * @method Sticker[] getStickers()      List of all set stickers
+ * @method PhotoSize getThumb()         Optional. Sticker set thumbnail in the .WEBP or .TGS format
  */
 class StickerSet extends Entity
 {
@@ -31,6 +32,7 @@ protected function subEntities()
     {
         return [
             'stickers' => [Sticker::class],
+            'thumb'    => PhotoSize::class,
         ];
     }
 }

src/Request.php

@@ -46,6 +46,7 @@
  * @method static ServerResponse sendVenue(array $data)                       Use this method to send information about a venue. On success, the sent Message is returned.
  * @method static ServerResponse sendContact(array $data)                     Use this method to send phone contacts. On success, the sent Message is returned.
  * @method static ServerResponse sendPoll(array $data)                        Use this method to send a native poll. A native poll can't be sent to a private chat. On success, the sent Message is returned.
+ * @method static ServerResponse sendDice(array $data)                        Use this method to send a dice, which will have a random value from 1 to 6. On success, the sent Message is returned.
  * @method static ServerResponse sendChatAction(array $data)                  Use this method when you need to tell the user that something is happening on the bot's side. The status is set for 5 seconds or less (when a message arrives from your bot, Telegram clients clear its typing status). Returns True on success.
  * @method static ServerResponse getUserProfilePhotos(array $data)            Use this method to get a list of profile pictures for a user. Returns a UserProfilePhotos object.
  * @method static ServerResponse getFile(array $data)                         Use this method to get basic info about a file and prepare it for downloading. For the moment, bots can download files of up to 20MB in size. On success, a File object is returned. The file can then be downloaded via the link https://api.telegram.org/file/bot<token>/<file_path>, where <file_path> is taken from the response. It is guaranteed that the link will be valid for at least 1 hour. When the link expires, a new one can be requested by calling getFile again.
@@ -71,6 +72,8 @@
  * @method static ServerResponse deleteChatStickerSet(array $data)            Use this method to delete a group sticker set from a supergroup. The bot must be an administrator in the chat for this to work and must have the appropriate admin rights. Use the field can_set_sticker_set optionally returned in getChat requests to check if the bot can use this method. Returns True on success.
  * @method static ServerResponse answerCallbackQuery(array $data)             Use this method to send answers to callback queries sent from inline keyboards. The answer will be displayed to the user as a notification at the top of the chat screen or as an alert. On success, True is returned.
  * @method static ServerResponse answerInlineQuery(array $data)               Use this method to send answers to an inline query. On success, True is returned.
+ * @method static ServerResponse setMyCommands(array $data)                   Use this method to change the list of the bot's commands. Returns True on success.
+ * @method static ServerResponse getMyCommands()                              Use this method to get the current list of the bot's commands. Requires no parameters. Returns Array of BotCommand on success.
  * @method static ServerResponse editMessageText(array $data)                 Use this method to edit text and game messages sent by the bot or via the bot (for inline bots). On success, if edited message is sent by the bot, the edited Message is returned, otherwise True is returned.
  * @method static ServerResponse editMessageCaption(array $data)              Use this method to edit captions of messages sent by the bot or via the bot (for inline bots). On success, if edited message is sent by the bot, the edited Message is returned, otherwise True is returned.
  * @method static ServerResponse editMessageMedia(array $data)                Use this method to edit audio, document, photo, or video messages. On success, if the edited message was sent by the bot, the edited Message is returned, otherwise True is returned.
@@ -83,6 +86,7 @@
  * @method static ServerResponse addStickerToSet(array $data)                 Use this method to add a new sticker to a set created by the bot. Returns True on success.
  * @method static ServerResponse setStickerPositionInSet(array $data)         Use this method to move a sticker in a set created by the bot to a specific position. Returns True on success.
  * @method static ServerResponse deleteStickerFromSet(array $data)            Use this method to delete a sticker from a set created by the bot. Returns True on success.
+ * @method static ServerResponse setStickerSetThumb(array $data)              Use this method to set the thumbnail of a sticker set. Animated thumbnails can be set for animated sticker sets only. Returns True on success.
  * @method static ServerResponse sendInvoice(array $data)                     Use this method to send invoices. On success, the sent Message is returned.
  * @method static ServerResponse answerShippingQuery(array $data)             If you sent an invoice requesting a shipping address and the parameter is_flexible was specified, the Bot API will send an Update with a shipping_query field to the bot. Use this method to reply to shipping queries. On success, True is returned.
  * @method static ServerResponse answerPreCheckoutQuery(array $data)          Once the user has confirmed their payment and shipping details, the Bot API sends the final confirmation in the form of an Update with the field pre_checkout_query. Use this method to respond to such pre-checkout queries. On success, True is returned.
@@ -167,6 +171,7 @@ class Request
         'sendVenue',
         'sendContact',
         'sendPoll',
+        'sendDice',
         'sendChatAction',
         'getUserProfilePhotos',
         'getFile',
@@ -192,6 +197,8 @@ class Request
         'deleteChatStickerSet',
         'answerCallbackQuery',
         'answerInlineQuery',
+        'setMyCommands',
+        'getMyCommands',
         'editMessageText',
         'editMessageCaption',
         'editMessageMedia',
@@ -204,6 +211,7 @@ class Request
         'addStickerToSet',
         'setStickerPositionInSet',
         'deleteStickerFromSet',
+        'setStickerSetThumb',
         'sendInvoice',
         'answerShippingQuery',
         'answerPreCheckoutQuery',
@@ -224,6 +232,7 @@ class Request
         'deleteWebhook',
         'getWebhookInfo',
         'getMe',
+        'getMyCommands',
     ];
 
     /**
@@ -246,8 +255,9 @@ class Request
         'setChatPhoto'        => ['photo'],
         'sendSticker'         => ['sticker'],
         'uploadStickerFile'   => ['png_sticker'],
-        'createNewStickerSet' => ['png_sticker'],
-        'addStickerToSet'     => ['png_sticker'],
+        'createNewStickerSet' => ['png_sticker', 'tgs_sticker'],
+        'addStickerToSet'     => ['png_sticker', 'tgs_sticker'],
+        'setStickerSetThumb'  => ['thumb'],
     ];
 
     /**
@@ -806,9 +816,11 @@ private static function limitTelegramRequests($action, array $data = [])
                 'sendVenue',
                 'sendContact',
                 'sendPoll',
+                'sendDice',
                 'sendInvoice',
                 'sendGame',
                 'setGameScore',
+                'setMyCommands',
                 'editMessageText',
                 'editMessageCaption',
                 'editMessageMedia',

structure.sql

@@ -100,6 +100,7 @@ CREATE TABLE IF NOT EXISTS `message` (
   `location` TEXT COMMENT 'Location object. Message is a shared location, information about the location',
   `venue` TEXT COMMENT 'Venue object. Message is a Venue, information about the Venue',
   `poll` TEXT COMMENT 'Poll object. Message is a native poll, information about the poll',
+  `dice` TEXT COMMENT 'Message is a dice with random value from 1 to 6',
   `new_chat_members` TEXT COMMENT 'List of unique user identifiers, new member(s) were added to the group, information about them (one of these members may be the bot itself)',
   `left_chat_member` bigint NULL DEFAULT NULL COMMENT 'Unique user identifier, a member was removed from the group, information about them (this member may be the bot itself)',
   `new_chat_title` CHAR(255) DEFAULT NULL COMMENT 'A chat title was changed to this value',

utils/db-schema-update/0.61.1-unreleased.sql

@@ -3,6 +3,7 @@ ALTER TABLE `poll` ADD COLUMN `is_anonymous` tinyint(1) DEFAULT 1 COMMENT 'True,
 ALTER TABLE `poll` ADD COLUMN `type` char(255) COMMENT 'Poll type, currently can be “regular” or “quiz”' AFTER `is_anonymous`;
 ALTER TABLE `poll` ADD COLUMN `allows_multiple_answers` tinyint(1) DEFAULT 0 COMMENT 'True, if the poll allows multiple answers' AFTER `type`;
 ALTER TABLE `poll` ADD COLUMN `correct_option_id` int UNSIGNED COMMENT '0-based identifier of the correct answer option. Available only for polls in the quiz mode, which are closed, or was sent (not forwarded) by the bot or to the private chat with the bot.' AFTER `allows_multiple_answers`;
+ALTER TABLE `message` ADD COLUMN `dice` TEXT COMMENT 'Message is a dice with random value from 1 to 6' AFTER `poll`;
 
 CREATE TABLE IF NOT EXISTS `poll_answer` (
   `poll_id` bigint UNSIGNED COMMENT 'Unique poll identifier',