Merge pull request #1082 from noplanman/1081-bot_api_4.8

Add new Bot API 4.8 fields to Poll and Dice entities and DB.

Author: noplanman

CHANGELOG.md

@@ -8,6 +8,7 @@ Exclamation symbols (:exclamation:) note something of importance e.g. breaking c
 - [:ledger: View file changes][Unreleased]
 ### Added
 - Replaced 'generic' and 'genericmessage' strings with Telegram::GENERIC_COMMAND and Telegram::GENERIC_MESSAGE_COMMAND constants (@1int)
+- Bot API 4.8 (Extra Poll and Dice features).
 ### Changed
 ### Deprecated
 ### Removed

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.7%20%28March%202020%29-32a2da.svg)](https://core.telegram.org/bots/api#december-31-2019)
+[![API Version](https://img.shields.io/badge/Bot%20API-4.8%20%28April%202020%29-32a2da.svg)](https://core.telegram.org/bots/api#april-24-2020)
 [![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.7 (March 2020).
+- Supports all types and methods according to Telegram Bot API 4.8 (April 2020).
 - Supports supergroups.
 - Handle commands in chat with other bots.
 - Manage Channel from the bot admin interface.

src/DB.php

@@ -837,17 +837,21 @@ public static function insertPollRequest(Poll $poll)
         try {
             $sth = self::$pdo->prepare('
                 INSERT INTO `' . TB_POLL . '`
-                (`id`, `question`, `options`, `total_voter_count`, `is_closed`, `is_anonymous`, `type`, `allows_multiple_answers`, `correct_option_id`, `created_at`)
+                (`id`, `question`, `options`, `total_voter_count`, `is_closed`, `is_anonymous`, `type`, `allows_multiple_answers`, `correct_option_id`, `explanation`, `explanation_entities`, `open_period`, `close_date`, `created_at`)
                 VALUES
-                (:id, :question, :options, :total_voter_count, :is_closed, :is_anonymous, :type, :allows_multiple_answers, :correct_option_id, :created_at)
+                (:id, :question, :options, :total_voter_count, :is_closed, :is_anonymous, :type, :allows_multiple_answers, :correct_option_id, :explanation, :explanation_entities, :open_period, :close_date, :created_at)
                 ON DUPLICATE KEY UPDATE
                     `options`                 = VALUES(`options`),
                     `total_voter_count`       = VALUES(`total_voter_count`),
                     `is_closed`               = VALUES(`is_closed`),
                     `is_anonymous`            = VALUES(`is_anonymous`),
                     `type`                    = VALUES(`type`),
                     `allows_multiple_answers` = VALUES(`allows_multiple_answers`),
-                    `correct_option_id`       = VALUES(`correct_option_id`)
+                    `correct_option_id`       = VALUES(`correct_option_id`),
+                    `explanation`             = VALUES(`explanation`),
+                    `explanation_entities`    = VALUES(`explanation_entities`),
+                    `open_period`             = VALUES(`open_period`),
+                    `close_date`              = VALUES(`close_date`)
             ');
 
             $sth->bindValue(':id', $poll->getId());
@@ -859,6 +863,10 @@ public static function insertPollRequest(Poll $poll)
             $sth->bindValue(':type', $poll->getType());
             $sth->bindValue(':allows_multiple_answers', $poll->getAllowsMultipleAnswers(), PDO::PARAM_INT);
             $sth->bindValue(':correct_option_id', $poll->getCorrectOptionId());
+            $sth->bindValue(':explanation', $poll->getExplanation());
+            $sth->bindValue(':explanation_entities', self::entitiesArrayToJson($poll->getExplanationEntities() ?: null));
+            $sth->bindValue(':open_period', $poll->getOpenPeriod());
+            $sth->bindValue(':close_date', self::getTimestamp($poll->getCloseDate()));
             $sth->bindValue(':created_at', self::getTimestamp());
 
             return $sth->execute();

src/Entities/Dice.php

@@ -18,7 +18,8 @@
  *
  * @link https://core.telegram.org/bots/api#dice
  *
- * @method int getValue() Value of the dice, 1-6
+ * @method string getEmoji() Emoji on which the dice throw animation is based
+ * @method int    getValue() Value of the dice, 1-6
  */
 class Dice extends Entity
 {

src/Entities/Poll.php

@@ -18,16 +18,19 @@
  *
  * @link https://core.telegram.org/bots/api#poll
  *
- * @method string       getId()                    Unique poll identifier
- * @method string       getQuestion()              Poll question, 1-255 characters
- * @method PollOption[] getOptions()               List of poll options
- * @method int          getTotalVoterCount()       Total number of users that voted in the poll
- * @method bool         getIsClosed()              True, if the poll is closed
- * @method bool         getIsAnonymous()           True, if the poll is anonymous
- * @method string       getType()                  Poll type, currently can be “regular” or “quiz”
- * @method bool         getAllowsMultipleAnswers() True, if the poll allows multiple answers
- * @method int          getCorrectOptionId()       Optional. 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.
-
+ * @method string          getId()                    Unique poll identifier
+ * @method string          getQuestion()              Poll question, 1-255 characters
+ * @method PollOption[]    getOptions()               List of poll options
+ * @method int             getTotalVoterCount()       Total number of users that voted in the poll
+ * @method bool            getIsClosed()              True, if the poll is closed
+ * @method bool            getIsAnonymous()           True, if the poll is anonymous
+ * @method string          getType()                  Poll type, currently can be “regular” or “quiz”
+ * @method bool            getAllowsMultipleAnswers() True, if the poll allows multiple answers
+ * @method int             getCorrectOptionId()       Optional. 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.
+ * @method string          getExplanation()           Optional. Text that is shown when a user chooses an incorrect answer or taps on the lamp icon in a quiz-style poll, 0-200 characters
+ * @method MessageEntity[] getExplanationEntities()   Optional. Special entities like usernames, URLs, bot commands, etc. that appear in the explanation
+ * @method int             getOpenPeriod()            Optional. Amount of time in seconds the poll will be active after creation
+ * @method int             getCloseDate()             Optional. Point in time (Unix timestamp) when the poll will be automatically closed
  */
 class Poll extends Entity
 {
@@ -37,7 +40,8 @@ class Poll extends Entity
     protected function subEntities()
     {
         return [
-            'options' => [PollOption::class],
+            'options'              => [PollOption::class],
+            'explanation_entities' => [MessageEntity::class],
         ];
     }
 }

structure.sql

@@ -216,6 +216,10 @@ CREATE TABLE IF NOT EXISTS `poll` (
   `type` char(255) COMMENT 'Poll type, currently can be “regular” or “quiz”',
   `allows_multiple_answers` tinyint(1) DEFAULT 0 COMMENT 'True, if the poll allows multiple answers',
   `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.',
+  `explanation` varchar(255) DEFAULT NULL COMMENT 'Text that is shown when a user chooses an incorrect answer or taps on the lamp icon in a quiz-style poll, 0-200 characters',
+  `explanation_entities` text DEFAULT NULL COMMENT 'Special entities like usernames, URLs, bot commands, etc. that appear in the explanation',
+  `open_period` int UNSIGNED DEFAULT NULL COMMENT 'Amount of time in seconds the poll will be active after creation',
+  `close_date` timestamp NULL DEFAULT NULL COMMENT 'Point in time (Unix timestamp) when the poll will be automatically closed',
   `created_at` timestamp NULL DEFAULT NULL COMMENT 'Entry date creation',
 
   PRIMARY KEY (`id`)

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

@@ -0,0 +1,4 @@
+ALTER TABLE `poll` ADD COLUMN `explanation` varchar(255) DEFAULT NULL COMMENT 'Text that is shown when a user chooses an incorrect answer or taps on the lamp icon in a quiz-style poll, 0-200 characters' AFTER `correct_option_id`;
+ALTER TABLE `poll` ADD COLUMN `explanation_entities` text DEFAULT NULL COMMENT 'Special entities like usernames, URLs, bot commands, etc. that appear in the explanation' AFTER `explanation`;
+ALTER TABLE `poll` ADD COLUMN `open_period` int UNSIGNED DEFAULT NULL COMMENT 'Amount of time in seconds the poll will be active after creation' AFTER `explanation_entities`;
+ALTER TABLE `poll` ADD COLUMN `close_date` timestamp NULL DEFAULT NULL COMMENT 'Point in time (Unix timestamp) when the poll will be automatically closed' AFTER `open_period`;