Add native Polls thanks to Bot API 4.2

Author: noplanman

CHANGELOG.md

@@ -6,6 +6,7 @@ Exclamation symbols (:exclamation:) note something of importance e.g. breaking c
 ## [Unreleased]
 :exclamation: After updating to this version, you will need to execute the [SQL migration script][unreleased-sql-migration] on your database.
 ### Added
+- Bot API 4.2 (Polls).
 - `getIsMember()` method to `ChatMember` entity.
 - `getForwardSenderName()` method to `Message` entity.
 - `forward_sender_name` (and forgotten `forward_signature`) DB fields.

src/DB.php

@@ -831,7 +831,7 @@ public static function insertMessageRequest(Message $message)
                     `forward_signature`, `forward_sender_name`, `forward_date`,
                     `reply_to_chat`, `reply_to_message`, `media_group_id`, `text`, `entities`, `audio`, `document`,
                     `animation`, `game`, `photo`, `sticker`, `video`, `voice`, `video_note`, `caption`, `contact`,
-                    `location`, `venue`, `new_chat_members`, `left_chat_member`,
+                    `location`, `venue`, `poll`, `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_from_chat_id`, `migrate_to_chat_id`, `pinned_message`, `connected_website`, `passport_data`
@@ -840,7 +840,7 @@ public static function insertMessageRequest(Message $message)
                     :forward_signature, :forward_sender_name, :forward_date,
                     :reply_to_chat, :reply_to_message, :media_group_id, :text, :entities, :audio, :document,
                     :animation, :game, :photo, :sticker, :video, :voice, :video_note, :caption, :contact,
-                    :location, :venue, :new_chat_members, :left_chat_member,
+                    :location, :venue, :poll, :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_from_chat_id, :migrate_to_chat_id, :pinned_message, :connected_website, :passport_data
@@ -896,6 +896,7 @@ public static function insertMessageRequest(Message $message)
             $sth->bindValue(':contact', $message->getContact());
             $sth->bindValue(':location', $message->getLocation());
             $sth->bindValue(':venue', $message->getVenue());
+            $sth->bindValue(':poll', $message->getPoll());
             $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/Message.php

@@ -46,6 +46,7 @@
  * @method Contact           getContact()               Optional. Message is a shared contact, information about the contact
  * @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 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
  * @method bool              getDeleteChatPhoto()       Optional. Service message: the chat photo was deleted
@@ -87,6 +88,7 @@ protected function subEntities()
             'contact'            => Contact::class,
             'location'           => Location::class,
             'venue'              => Venue::class,
+            'poll'               => Poll::class,
             'new_chat_members'   => User::class,
             'left_chat_member'   => User::class,
             'new_chat_photo'     => PhotoSize::class,
@@ -296,6 +298,7 @@ public function getType()
             'contact',
             'location',
             'venue',
+            'poll',
             'new_chat_members',
             'left_chat_member',
             'new_chat_title',

src/Entities/Poll.php

@@ -0,0 +1,50 @@
+<?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 Poll
+ *
+ * This entity contains information about a poll.
+ *
+ * @link https://core.telegram.org/bots/api#poll
+ *
+ * @method string getId()       Unique poll identifier
+ * @method string getQuestion() Poll question, 1-255 characters
+ * @method bool   getIsClosed() True, if the poll is closed
+ */
+class Poll extends Entity
+{
+    /**
+     * {@inheritdoc}
+     */
+    protected function subEntities()
+    {
+        return [
+            'options' => PollOption::class,
+        ];
+    }
+
+    /**
+     * List of poll options
+     *
+     * This method overrides the default getOptions method
+     * and returns a nice array of PollOption objects.
+     *
+     * @return null|PollOption[]
+     */
+    public function getOptions()
+    {
+        $pretty_array = $this->makePrettyObjectArray(PollOption::class, 'options');
+
+        return empty($pretty_array) ? null : $pretty_array;
+    }
+}

src/Entities/PollOption.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 PollOption
+ *
+ * This entity contains information about one answer option in a poll.
+ *
+ * @link https://core.telegram.org/bots/api#polloption
+ *
+ * @method string getText()       Option text, 1-100 characters
+ * @method int    getVoterCount() Number of users that voted for this option
+ */
+class PollOption extends Entity
+{
+
+}

src/Entities/Update.php

@@ -28,6 +28,7 @@
  * @method CallbackQuery       getCallbackQuery()      Optional. New incoming callback query
  * @method ShippingQuery       getShippingQuery()      Optional. New incoming shipping query. Only for invoices with flexible price
  * @method PreCheckoutQuery    getPreCheckoutQuery()   Optional. New incoming pre-checkout query. Contains full information about checkout
+ * @method Poll                getPoll()               Optional. New poll state. Bots receive only updates about polls, which are sent or stopped by the bot
  */
 class Update extends Entity
 {
@@ -46,6 +47,7 @@ protected function subEntities()
             'callback_query'       => CallbackQuery::class,
             'shipping_query'       => ShippingQuery::class,
             'pre_checkout_query'   => PreCheckoutQuery::class,
+            'poll'                 => Poll::class,
         ];
     }
 
@@ -66,6 +68,7 @@ public function getUpdateType()
             'callback_query',
             'shipping_query',
             'pre_checkout_query',
+            'poll',
         ];
         foreach ($types as $type) {
             if ($this->getProperty($type)) {

src/Request.php

@@ -42,6 +42,7 @@
  * @method static ServerResponse stopMessageLiveLocation(array $data) Use this method to stop updating a live location message sent by the bot or via the bot (for inline bots) before live_period expires. On success, if the message was sent by the bot, the sent Message is returned, otherwise True is returned.
  * @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 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.
@@ -69,6 +70,7 @@
  * @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.
  * @method static ServerResponse editMessageReplyMarkup(array $data)  Use this method to edit only the reply markup 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 stopPoll(array $data)                Use this method to stop a poll which was sent by the bot. On success, the stopped Poll with the final results is returned.
  * @method static ServerResponse deleteMessage(array $data)           Use this method to delete a message, including service messages, with certain limitations. Returns True on success.
  * @method static ServerResponse getStickerSet(array $data)           Use this method to get a sticker set. On success, a StickerSet object is returned.
  * @method static ServerResponse uploadStickerFile(array $data)       Use this method to upload a .png file with a sticker for later use in createNewStickerSet and addStickerToSet methods (can be used multiple times). Returns the uploaded File on success.
@@ -166,6 +168,7 @@ class Request
         'stopMessageLiveLocation',
         'sendVenue',
         'sendContact',
+        'sendPoll',
         'sendChatAction',
         'getUserProfilePhotos',
         'getFile',
@@ -193,6 +196,7 @@ class Request
         'editMessageCaption',
         'editMessageMedia',
         'editMessageReplyMarkup',
+        'stopPoll',
         'deleteMessage',
         'getStickerSet',
         'uploadStickerFile',
@@ -807,13 +811,15 @@ private static function limitTelegramRequests($action, array $data = [])
                 'stopMessageLiveLocation',
                 'sendVenue',
                 'sendContact',
+                'sendPoll',
                 'sendInvoice',
                 'sendGame',
                 'setGameScore',
                 'editMessageText',
                 'editMessageCaption',
                 'editMessageMedia',
                 'editMessageReplyMarkup',
+                'stopPoll',
                 'setChatTitle',
                 'setChatDescription',
                 'setChatStickerSet',

structure.sql

@@ -93,6 +93,7 @@ CREATE TABLE IF NOT EXISTS `message` (
   `contact` TEXT COMMENT 'Contact object. Message is a shared contact, information about the contact',
   `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',
   `caption` TEXT COMMENT  'For message with caption, the actual UTF-8 text of the caption',
   `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)',

utils/db-schema-update/unreleased.sql

@@ -1,2 +1,3 @@
 ALTER TABLE `message` ADD COLUMN `forward_signature` TEXT NULL DEFAULT NULL COMMENT 'For messages forwarded from channels, signature of the post author if present' AFTER `forward_from_message_id`;
 ALTER TABLE `message` ADD COLUMN `forward_sender_name` TEXT NULL DEFAULT NULL COMMENT 'Sender''s name for messages forwarded from users who disallow adding a link to their account in forwarded messages' AFTER `forward_signature`;
+ALTER TABLE `message` ADD COLUMN `poll` TEXT COMMENT 'Poll object. Message is a native poll, information about the poll' AFTER `venue`;