Merge pull request #1066 from noplanman/1049_bot_api_4.6

Bot API 4.6

Author: noplanman

CHANGELOG.md

@@ -10,6 +10,7 @@ Exclamation symbols (:exclamation:) note something of importance e.g. breaking c
 - Bot API 4.5 (Unique file IDs, MarkdownV2). (#1046)
 - 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).
 ### 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.5%20%28December%202019%29-32a2da.svg)](https://core.telegram.org/bots/api#december-31-2019)
+[![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)
 [![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.4 (July 2019).
+- Supports all types and methods according to Telegram API 4.6 (January 2020).
 - Supports supergroups.
 - Handle commands in chat with other bots.
 - Manage Channel from the bot admin interface.

src/DB.php

@@ -20,6 +20,7 @@
 use Longman\TelegramBot\Entities\Payments\PreCheckoutQuery;
 use Longman\TelegramBot\Entities\Payments\ShippingQuery;
 use Longman\TelegramBot\Entities\Poll;
+use Longman\TelegramBot\Entities\PollAnswer;
 use Longman\TelegramBot\Entities\Update;
 use Longman\TelegramBot\Entities\User;
 use Longman\TelegramBot\Exception\TelegramException;
@@ -145,6 +146,7 @@ protected static function defineTables()
             'message',
             'pre_checkout_query',
             'poll',
+            'poll_answer',
             'request_limiter',
             'shipping_query',
             'telegram_update',
@@ -317,6 +319,7 @@ public static function entitiesArrayToJson($entities, $default = null)
      * @param string|null $shipping_query_id
      * @param string|null $pre_checkout_query_id
      * @param string|null $poll_id
+     * @param string|null $poll_answer_poll_id
      *
      * @return bool If the insert was successful
      * @throws TelegramException
@@ -333,10 +336,11 @@ protected static function insertTelegramUpdate(
         $callback_query_id = null,
         $shipping_query_id = null,
         $pre_checkout_query_id = null,
-        $poll_id = null
+        $poll_id = null,
+        $poll_answer_poll_id = null
     ) {
-        if ($message_id === null && $edited_message_id === null && $channel_post_id === null && $edited_channel_post_id === null && $inline_query_id === null && $chosen_inline_result_id === null && $callback_query_id === null && $shipping_query_id === null && $pre_checkout_query_id === null && $poll_id === null) {
-            throw new TelegramException('message_id, edited_message_id, channel_post_id, edited_channel_post_id, inline_query_id, chosen_inline_result_id, callback_query_id, shipping_query_id, pre_checkout_query_id, poll_id are all null');
+        if ($message_id === null && $edited_message_id === null && $channel_post_id === null && $edited_channel_post_id === null && $inline_query_id === null && $chosen_inline_result_id === null && $callback_query_id === null && $shipping_query_id === null && $pre_checkout_query_id === null && $poll_id === null && $poll_answer_poll_id === null) {
+            throw new TelegramException('message_id, edited_message_id, channel_post_id, edited_channel_post_id, inline_query_id, chosen_inline_result_id, callback_query_id, shipping_query_id, pre_checkout_query_id, poll_id, poll_answer_poll_id are all null');
         }
 
         if (!self::isDbConnected()) {
@@ -346,9 +350,9 @@ protected static function insertTelegramUpdate(
         try {
             $sth = self::$pdo->prepare('
                 INSERT IGNORE INTO `' . TB_TELEGRAM_UPDATE . '`
-                (`id`, `chat_id`, `message_id`, `edited_message_id`, `channel_post_id`, `edited_channel_post_id`, `inline_query_id`, `chosen_inline_result_id`, `callback_query_id`, `shipping_query_id`, `pre_checkout_query_id`, `poll_id`)
+                (`id`, `chat_id`, `message_id`, `edited_message_id`, `channel_post_id`, `edited_channel_post_id`, `inline_query_id`, `chosen_inline_result_id`, `callback_query_id`, `shipping_query_id`, `pre_checkout_query_id`, `poll_id`, `poll_answer_poll_id`)
                 VALUES
-                (:id, :chat_id, :message_id, :edited_message_id, :channel_post_id, :edited_channel_post_id, :inline_query_id, :chosen_inline_result_id, :callback_query_id, :shipping_query_id, :pre_checkout_query_id, :poll_id)
+                (:id, :chat_id, :message_id, :edited_message_id, :channel_post_id, :edited_channel_post_id, :inline_query_id, :chosen_inline_result_id, :callback_query_id, :shipping_query_id, :pre_checkout_query_id, :poll_id, :poll_answer_poll_id)
             ');
 
             $sth->bindValue(':id', $update_id);
@@ -363,6 +367,7 @@ protected static function insertTelegramUpdate(
             $sth->bindValue(':shipping_query_id', $shipping_query_id);
             $sth->bindValue(':pre_checkout_query_id', $pre_checkout_query_id);
             $sth->bindValue(':poll_id', $poll_id);
+            $sth->bindValue(':poll_answer_poll_id', $poll_answer_poll_id);
 
             return $sth->execute();
         } catch (PDOException $e) {
@@ -526,6 +531,7 @@ public static function insertRequest(Update $update)
         $shipping_query_id       = null;
         $pre_checkout_query_id   = null;
         $poll_id                 = null;
+        $poll_answer_poll_id     = null;
 
         if (($message = $update->getMessage()) && self::insertMessageRequest($message)) {
             $chat_id    = $message->getChat()->getId();
@@ -551,6 +557,8 @@ public static function insertRequest(Update $update)
             $pre_checkout_query_id = $pre_checkout_query->getId();
         } elseif (($poll = $update->getPoll()) && self::insertPollRequest($poll)) {
             $poll_id = $poll->getId();
+        } elseif (($poll_answer = $update->getPollAnswer()) && self::insertPollAnswerRequest($poll_answer)) {
+            $poll_answer_poll_id = $poll_answer->getPollId();
         } else {
             return false;
         }
@@ -567,7 +575,8 @@ public static function insertRequest(Update $update)
             $callback_query_id,
             $shipping_query_id,
             $pre_checkout_query_id,
-            $poll_id
+            $poll_id,
+            $poll_answer_poll_id
         );
     }
 
@@ -828,18 +837,28 @@ public static function insertPollRequest(Poll $poll)
         try {
             $sth = self::$pdo->prepare('
                 INSERT INTO `' . TB_POLL . '`
-                (`id`, `question`, `options`, `is_closed`, `created_at`)
+                (`id`, `question`, `options`, `total_voter_count`, `is_closed`, `is_anonymous`, `type`, `allows_multiple_answers`, `correct_option_id`, `created_at`)
                 VALUES
-                (:id, :question, :options, :is_closed, :created_at)
+                (:id, :question, :options, :total_voter_count, :is_closed, :is_anonymous, :type, :allows_multiple_answers, :correct_option_id, :created_at)
                 ON DUPLICATE KEY UPDATE
-                    `options`   = VALUES(`options`),
-                    `is_closed` = VALUES(`is_closed`)
+                    `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`)
             ');
 
             $sth->bindValue(':id', $poll->getId());
             $sth->bindValue(':question', $poll->getQuestion());
             $sth->bindValue(':options', self::entitiesArrayToJson($poll->getOptions() ?: null));
+            $sth->bindValue(':total_voter_count', $poll->getTotalVoterCount());
             $sth->bindValue(':is_closed', $poll->getIsClosed(), PDO::PARAM_INT);
+            $sth->bindValue(':is_anonymous', $poll->getIsAnonymous(), PDO::PARAM_INT);
+            $sth->bindValue(':type', $poll->getType());
+            $sth->bindValue(':allows_multiple_answers', $poll->getAllowsMultipleAnswers(), PDO::PARAM_INT);
+            $sth->bindValue(':correct_option_id', $poll->getCorrectOptionId());
             $sth->bindValue(':created_at', self::getTimestamp());
 
             return $sth->execute();
@@ -848,6 +867,49 @@ public static function insertPollRequest(Poll $poll)
         }
     }
 
+    /**
+     * Insert poll answer request into database
+     *
+     * @param PollAnswer $poll_answer
+     *
+     * @return bool If the insert was successful
+     * @throws TelegramException
+     */
+    public static function insertPollAnswerRequest(PollAnswer $poll_answer)
+    {
+        if (!self::isDbConnected()) {
+            return false;
+        }
+
+        try {
+            $sth = self::$pdo->prepare('
+                INSERT INTO `' . TB_POLL_ANSWER . '`
+                (`poll_id`, `user_id`, `option_ids`, `created_at`)
+                VALUES
+                (:poll_id, :user_id, :option_ids, :created_at)
+                ON DUPLICATE KEY UPDATE
+                    `option_ids` = VALUES(`option_ids`)
+            ');
+
+            $date    = self::getTimestamp();
+            $user_id = null;
+
+            if ($user = $poll_answer->getUser()) {
+                $user_id = $user->getId();
+                self::insertUser($user, $date);
+            }
+
+            $sth->bindValue(':poll_id', $poll_answer->getPollId());
+            $sth->bindValue(':user_id', $user_id);
+            $sth->bindValue(':option_ids', json_encode($poll_answer->getOptionIds()));
+            $sth->bindValue(':created_at', $date);
+
+            return $sth->execute();
+        } catch (PDOException $e) {
+            throw new TelegramException($e->getMessage());
+        }
+    }
+
     /**
      * Insert Message request in db
      *

src/Entities/KeyboardButton.php

@@ -16,18 +16,23 @@
 /**
  * Class KeyboardButton
  *
+ * This object represents one button of the reply keyboard. For simple text buttons String can be used instead of this object to specify text of the button. Optional fields request_contact, request_location, and request_poll are mutually exclusive.
+ *
  * @link https://core.telegram.org/bots/api#keyboardbutton
  *
- * @property bool $request_contact
- * @property bool $request_location
+ * @property bool                   $request_contact
+ * @property bool                   $request_location
+ * @property KeyboardButtonPollType $request_poll
  *
- * @method string getText()            Text of the button. If none of the optional fields are used, it will be sent to the bot as a message when the button is pressed
- * @method bool   getRequestContact()  Optional. If True, the user's phone number will be sent as a contact when the button is pressed. Available in private chats only
- * @method bool   getRequestLocation() Optional. If True, the user's current location will be sent when the button is pressed. Available in private chats only
+ * @method string                 getText()            Text of the button. If none of the optional fields are used, it will be sent to the bot as a message when the button is pressed
+ * @method bool                   getRequestContact()  Optional. If True, the user's phone number will be sent as a contact when the button is pressed. Available in private chats only
+ * @method bool                   getRequestLocation() Optional. If True, the user's current location will be sent when the button is pressed. Available in private chats only
+ * @method KeyboardButtonPollType getRequestPoll() Optional. If specified, the user will be asked to create a poll and send it to the bot when the button is pressed. Available in private chats only
  *
- * @method $this setText(string $text)                      Text of the button. If none of the optional fields are used, it will be sent to the bot as a message when the button is pressed
- * @method $this setRequestContact(bool $request_contact)   Optional. If True, the user's phone number will be sent as a contact when the button is pressed. Available in private chats only
- * @method $this setRequestLocation(bool $request_location) Optional. If True, the user's current location will be sent when the button is pressed. Available in private chats only
+ * @method $this setText(string $text)                                Text of the button. If none of the optional fields are used, it will be sent to the bot as a message when the button is pressed
+ * @method $this setRequestContact(bool $request_contact)             Optional. If True, the user's phone number will be sent as a contact when the button is pressed. Available in private chats only
+ * @method $this setRequestLocation(bool $request_location)           Optional. If True, the user's current location will be sent when the button is pressed. Available in private chats only
+ * @method $this setRequestPoll(KeyboardButtonPollType $request_poll) Optional. If specified, the user will be asked to create a poll and send it to the bot when the button is pressed. Available in private chats only
  */
 class KeyboardButton extends Entity
 {
@@ -63,8 +68,14 @@ protected function validate()
             throw new TelegramException('You must add some text to the button!');
         }
 
-        if ($this->getRequestContact() && $this->getRequestLocation()) {
-            throw new TelegramException('You must use only one of these fields: request_contact, request_location!');
+        // Make sure only 1 of the optional request fields is set.
+        $field_count = array_filter([
+            $this->getRequestContact(),
+            $this->getRequestLocation(),
+            $this->getRequestPoll(),
+        ]);
+        if (count($field_count) > 1) {
+            throw new TelegramException('You must use only one of these fields: request_contact, request_location, request_poll!');
         }
     }
 
@@ -74,8 +85,8 @@ protected function validate()
     public function __call($method, $args)
     {
         // Only 1 of these can be set, so clear the others when setting a new one.
-        if (in_array($method, ['setRequestContact', 'setRequestLocation'], true)) {
-            unset($this->request_contact, $this->request_location);
+        if (in_array($method, ['setRequestContact', 'setRequestLocation', 'setRequestPoll'], true)) {
+            unset($this->request_contact, $this->request_location, $this->request_poll);
         }
 
         return parent::__call($method, $args);

src/Entities/KeyboardButtonPollType.php

@@ -0,0 +1,28 @@
+<?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 KeyboardButtonPollType
+ *
+ * This entity represents type of a poll, which is allowed to be created and sent when the corresponding button is pressed.
+ *
+ * @link https://core.telegram.org/bots/api#keyboardbutton
+ *
+ * @method string getType() Optional. If 'quiz' is passed, the user will be allowed to create only polls in the quiz mode. If 'regular' is passed, only regular polls will be allowed. Otherwise, the user will be allowed to create a poll of any type.
+ *
+ * @method $this setType(string $type) Optional. If 'quiz' is passed, the user will be allowed to create only polls in the quiz mode. If 'regular' is passed, only regular polls will be allowed. Otherwise, the user will be allowed to create a poll of any type.
+ */
+class KeyboardButtonPollType extends Entity
+{
+
+}

src/Entities/MessageEntity.php

@@ -16,11 +16,12 @@
  *
  * @link https://core.telegram.org/bots/api#messageentity
  *
- * @method string getType()   Type of the entity. Can be 'mention' (@username), 'hashtag' (#hashtag), 'cashtag' ($USD), 'bot_command' (/start@jobs_bot), 'url' (https://telegram.org), 'email' ([email protected]), 'phone_number' (+1-212-555-0123), 'bold' (bold text), 'italic' (italic text), 'underline' (underlined text), 'strikethrough' (strikethrough text), 'code' (monowidth string), 'pre' (monowidth block), 'text_link' (for clickable text URLs), 'text_mention' (for users without usernames)
- * @method int    getOffset() Offset in UTF-16 code units to the start of the entity
- * @method int    getLength() Length of the entity in UTF-16 code units
- * @method string getUrl()    Optional. For "text_link" only, url that will be opened after user taps on the text
- * @method User   getUser()   Optional. For "text_mention" only, the mentioned user
+ * @method string getType()     Type of the entity. Can be 'mention' (@username), 'hashtag' (#hashtag), 'cashtag' ($USD), 'bot_command' (/start@jobs_bot), 'url' (https://telegram.org), 'email' ([email protected]), 'phone_number' (+1-212-555-0123), 'bold' (bold text), 'italic' (italic text), 'underline' (underlined text), 'strikethrough' (strikethrough text), 'code' (monowidth string), 'pre' (monowidth block), 'text_link' (for clickable text URLs), 'text_mention' (for users without usernames)
+ * @method int    getOffset()   Offset in UTF-16 code units to the start of the entity
+ * @method int    getLength()   Length of the entity in UTF-16 code units
+ * @method string getUrl()      Optional. For "text_link" only, url that will be opened after user taps on the text
+ * @method User   getUser()     Optional. For "text_mention" only, the mentioned user
+ * @method string getLanguage() Optional. For "pre" only, the programming language of the entity text
  */
 class MessageEntity extends Entity
 {

src/Entities/Poll.php

@@ -18,10 +18,16 @@
  *
  * @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 bool         getIsClosed() True, if the poll is closed
+ * @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.
+
  */
 class Poll extends Entity
 {