Implements Poll support

Author: camilo.sperberg

README.md

@@ -1,6 +1,6 @@
-[![PHP 7 Telegram Bot API](https://github.com/unreal4u/telegram-api/blob/master/examples/binary-test-data/logo-php7-telegram-bot-api-small.png?raw=true)](https://github.com/unreal4u/telegram-api/wiki/100-stars!)
+[![PHP 7 Telegram Bot API Library](https://github.com/unreal4u/telegram-api/blob/master/examples/binary-test-data/logo-php7-telegram-bot-api-small.png?raw=true)](https://github.com/unreal4u/telegram-api/wiki/100-stars!)
 
-# Telegram API
+# Telegram API Library
 
 [![Latest Stable Version](https://poser.pugx.org/unreal4u/telegram-api/v/stable)](https://packagist.org/packages/unreal4u/telegram-api)
 [![Total Downloads](https://poser.pugx.org/unreal4u/telegram-api/downloads)](https://packagist.org/packages/unreal4u/telegram-api)
@@ -9,10 +9,11 @@
 [![Code Coverage](https://scrutinizer-ci.com/g/unreal4u/telegram-api/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/unreal4u/telegram-api/?branch=master)
 [![License](https://poser.pugx.org/unreal4u/telegram-api/license)](https://packagist.org/packages/unreal4u/telegram-api)
 
-This is a PHP7 bot API implementation for Telegram implementing the **totality** of [Bot API up until v3.6](https://core.telegram.org/bots/api#february-13-2018)
-and the vast majority of the [Bot API up until v4.1](https://core.telegram.org/bots/api#august-27-2018)
+This is a PHP7 bot API implementation for Telegram implementing the **vast majority** of
+[Bot API up until v4.3](https://core.telegram.org/bots/api#february-13-2018). The only thing it does not implement is
+Telegram Passport which was introduced in [Bot API v4.0](https://core.telegram.org/bots/api#july-26-2018).
 
-### About this class
+### About this package
 
 * Enables you to anything supported by the Telegram Bot API: messages, stickers, location, inline bots and any other supported method via PHP to a Telegram user (either direct conversation, channel, group or supergroup).
 * Respects and implements the default types and methods made by Telegram itself. Have any doubts about any method? [Just check the original documentation](https://core.telegram.org/bots/api), this implementation will not differ too much.
@@ -24,7 +25,8 @@ and the vast majority of the [Bot API up until v4.1](https://core.telegram.org/b
 
 [![Telegram](http://trellobot.doomdns.org/telegrambadge.svg)](https://t.me/PHPBotAPI)
 
-The only thing that is not included in this library (yet) is the Passport support. This will be implemented soon though!
+The only thing that is not included in this library (yet) is the Passport support. This was an ongoing development, but
+it ended up being a lot more work than initially thought, so if someone wants to pick that up... be my guest!
 
 All other known bugs can be found in the form of issues or pull requests. Found a new bug? Feel free to [submit a PR](https://github.com/unreal4u/telegram-api/pulls) or
 [create an issue](https://github.com/unreal4u/telegram-api/issues)! Not sure if you've found a new bug? You can always ask
@@ -34,7 +36,7 @@ in the [special group](https://t.me/PHPBotAPI) :)
 
 - v4 (no branch yet) will be the next major release. [More information](https://github.com/unreal4u/telegram-api/projects/5).
 - v3 (master branch) is the current active branch.
-- v2 (v2 branch) will be updated with the latest Bot API updates until v4 comes out (no plans for that yet, sorry!).
+- v2 (v2 branch) is deprecated and no new work will be done there.
 - v1 is deprecated and no new work will be done there.
 - v0 is deprecated and no new work will be done there.
 

src/Abstracts/TraversableCustomType.php

@@ -4,14 +4,28 @@
 
 namespace unreal4u\TelegramAPI\Abstracts;
 
+use ArrayIterator;
+use Generator;
+use IteratorAggregate;
+use Traversable;
+
 /**
- * Class TraversableType
+ * Class TraversableCustomType
  * @package unreal4u\TelegramAPI\Abstracts
  */
-abstract class TraversableCustomType extends CustomType implements \IteratorAggregate
+abstract class TraversableCustomType extends CustomType implements IteratorAggregate
 {
-    public function getIterator(): \Traversable
+    public function getIterator(): Traversable
+    {
+        return new ArrayIterator($this->data);
+    }
+
+    /**
+     * Traverses through our $data, yielding the result set, can return any type of object
+     * @return Generator|TelegramTypes
+     */
+    final public function traverseObject(): Generator
     {
-        return new \ArrayIterator($this->data);
+        yield from $this->data;
     }
 }

src/Telegram/Methods/SendPoll.php

@@ -0,0 +1,74 @@
+<?php
+
+declare(strict_types=1);
+
+namespace unreal4u\TelegramAPI\Telegram\Methods;
+
+use unreal4u\TelegramAPI\Abstracts\KeyboardMethods;
+use unreal4u\TelegramAPI\Abstracts\TelegramMethods;
+use function json_encode;
+
+/**
+ * Use this method to send point on the map. On success, the sent Message is returned.
+ *
+ * Objects defined as-is june 2019
+ *
+ * @see https://core.telegram.org/bots/api#sendpoll
+ */
+class SendPoll extends TelegramMethods
+{
+    /**
+     * Unique identifier for the target chat or username of the target channel (in the format @channelusername). A
+     * native poll can't be sent to a private chat
+     * @var string
+     */
+    public $chat_id = '';
+
+    /**
+     * Poll question, 1-255 characters
+     * @var string
+     */
+    public $question = '';
+
+    /**
+     * List of answer options, 2-10 strings 1-100 characters each
+     * @var string[]
+     */
+    public $options = [];
+
+    /**
+     * Optional. Sends the message silently. iOS users will not receive a notification, Android users will receive a
+     * notification with no sound.
+     * @see https://telegram.org/blog/channels-2-0#silent-messages
+     * @var bool
+     */
+    public $disable_notification = false;
+
+    /**
+     * If the message is a reply, ID of the original message
+     * @var int
+     */
+    public $reply_to_message_id = 0;
+
+    /**
+     * Optional. Additional interface options. A JSON-serialized object for a custom reply keyboard, instructions to
+     * hide keyboard or to force a reply from the user.
+     * @var KeyboardMethods
+     */
+    public $reply_markup;
+
+    public function getMandatoryFields(): array
+    {
+        return [
+            'chat_id',
+            'question',
+            'options',
+        ];
+    }
+
+    public function performSpecialConditions(): TelegramMethods
+    {
+        $this->options = json_encode($this->options);
+        return parent::performSpecialConditions();
+    }
+}

src/Telegram/Methods/StopPoll.php

@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+namespace unreal4u\TelegramAPI\Telegram\Methods;
+
+use unreal4u\TelegramAPI\Abstracts\KeyboardMethods;
+use unreal4u\TelegramAPI\Abstracts\TelegramMethods;
+
+/**
+ * Use this method to send point on the map. On success, the sent Message is returned.
+ *
+ * Objects defined as-is june 2019
+ *
+ * @see https://core.telegram.org/bots/api#stoppoll
+ */
+class StopPoll extends TelegramMethods
+{
+    /**
+     * Unique identifier for the target chat or username of the target channel (in the format @channelusername). A
+     * native poll can't be sent to a private chat
+     * @var string
+     */
+    public $chat_id = '';
+
+    /**
+     * Identifier of the original message with the poll
+     * @var int
+     */
+    public $message_id;
+
+    /**
+     * Optional. Additional interface options. A JSON-serialized object for a custom reply keyboard, instructions to
+     * hide keyboard or to force a reply from the user.
+     * @var KeyboardMethods
+     */
+    public $reply_markup;
+
+    public function getMandatoryFields(): array
+    {
+        return [
+            'chat_id',
+            'message_id',
+        ];
+    }
+}

src/Telegram/Types/Custom/MessageArray.php

@@ -22,16 +22,4 @@ public function __construct(array $data = null, LoggerInterface $logger = null)
             }
         }
     }
-
-    /**
-     * Traverses through our $data, yielding the result set
-     *
-     * @return Update[]
-     */
-    public function traverseObject()
-    {
-        foreach ($this->data as $message) {
-            yield $message;
-        }
-    }
 }

src/Telegram/Types/Custom/PassportFileArray.php

@@ -22,16 +22,4 @@ public function __construct(array $data = null, LoggerInterface $logger = null)
             }
         }
     }
-
-    /**
-     * Traverses through our $data, yielding the result set
-     *
-     * @return PhotoSize[]
-     */
-    public function traverseObject(): \Generator
-    {
-        foreach ($this->data as $passportFile) {
-            yield $passportFile;
-        }
-    }
 }

src/Telegram/Types/Custom/PollOptionArray.php

@@ -0,0 +1,25 @@
+<?php
+declare(strict_types=1);
+
+namespace unreal4u\TelegramAPI\Telegram\Types\Custom;
+
+use Psr\Log\LoggerInterface;
+use unreal4u\TelegramAPI\Abstracts\TraversableCustomType;
+use unreal4u\TelegramAPI\Telegram\Types\PollOption;
+use function count;
+
+/**
+ * Used for methods that will return an array of messages
+ */
+class PollOptionArray extends TraversableCustomType
+{
+    public function __construct(array $data = null, LoggerInterface $logger = null)
+    {
+        if (count($data) !== 0) {
+            foreach ($data as $telegramResponse) {
+                // Create an actual Update object and fill the array
+                $this->data[] = new PollOption($telegramResponse, $logger);
+            }
+        }
+    }
+}

src/Telegram/Types/Message.php

@@ -198,6 +198,12 @@ class Message extends TelegramTypes
      */
     public $venue;
 
+    /**
+     * Optional. Message is a native poll, information about the poll
+     * @var Poll
+     */
+    public $poll;
+
     /**
      * Optional. A new member was added to the group, information about them (this member may be the bot itself)
      * @var User
@@ -349,6 +355,8 @@ protected function mapSubObjects(string $key, array $data): TelegramTypes
                 return new Location($data, $this->logger);
             case 'venue':
                 return new Venue($data, $this->logger);
+            case 'poll':
+                return new Poll($data, $this->logger);
             case 'invoice':
                 return new Invoice($data, $this->logger);
             case 'successful_payment':

src/Telegram/Types/Poll.php

@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+namespace unreal4u\TelegramAPI\Telegram\Types;
+
+use unreal4u\TelegramAPI\Abstracts\TelegramTypes;
+use unreal4u\TelegramAPI\Telegram\Types\Custom\PollOptionArray;
+
+/**
+ * This object contains information about a poll
+ *
+ * Objects defined as-is june 2019
+ *
+ * @see https://core.telegram.org/bots/api#poll
+ */
+class Poll extends TelegramTypes
+{
+    /**
+     * Unique poll identifier
+     * @var string
+     */
+    public $id;
+
+    /**
+     * Poll question, 1-255 characters
+     * @var string
+     */
+    public $question = '';
+
+    /**
+     * List of poll options
+     * @var PollOption[]
+     */
+    public $options;
+
+    /**
+     * True, if the poll is closed
+     * @var bool
+     */
+    public $is_closed;
+
+    public function mapSubObjects(string $key, array $data): TelegramTypes
+    {
+        switch ($key) {
+            case 'options':
+                return new PollOptionArray($data, $this->logger);
+        }
+
+        return parent::mapSubObjects($key, $data); // TODO: Change the autogenerated stub
+    }
+}

src/Telegram/Types/PollOption.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace unreal4u\TelegramAPI\Telegram\Types;
+
+use unreal4u\TelegramAPI\Abstracts\TelegramTypes;
+
+/**
+ * This object contains information about a poll
+ *
+ * Objects defined as-is june 2019
+ *
+ * @see https://core.telegram.org/bots/api#polloption
+ */
+class PollOption extends TelegramTypes
+{
+    /**
+     * Option text, 1-100 characters
+     * @var string
+     */
+    public $text;
+
+    /**
+     * Number of users that voted for this option
+     * @var int
+     */
+    public $voter_count;
+}