Merge pull request #32 from tg-bot-api/feature/#31-bot-api-v-4.8

Feature/#31 bot api v 4.8

Author: greenplugin

CHANGELOG.md

@@ -22,6 +22,25 @@ Updates should follow the [Keep a CHANGELOG](http://keepachangelog.com/) princip
 ### Security
 - Nothing
 --->
+## 1.5.0 - 2020-04-24
+
+#### April 24, 2020
+#### Bot API 4.8
+
+### Added
+- Supported explanations for
+ [**Quizzes 2.0**](https://telegram.org/blog/400-million#better-quizzes). 
+Add explanations by specifying the parameters 
+explanation and `explanationParseMode` in the method `SendPollMethod`.
+- Added the fields explanation and `explanationEntities` to the `PollType` class.
+- Supported timed polls that automatically close at a certain date and time. 
+Set up by specifying the parameter `openPeriod` or `closeDate` in the `SendPollMethod`.
+- Added the fields `openPeriod` and `closeDate` to the `PollType` class.
+- Supported the new darts animation for the dice mini-game. 
+Choose between the default dice animation and darts animation 
+by specifying the parameter `emoji` in the `SendDiceMethod`. 
+Added two factory methods `createWithDice` and `createWithDarts`  for `SendDiceMethod`.
+- Added the field `emoji` to the `DiceType` class.
 
 ## 1.4.0 - 2020-03-31
 

README.md

@@ -14,7 +14,7 @@
 [![Duplicated Lines (%)][sonar-duplicated-lines-icon]][sonar-path]
 [![Security Rating][sonar-security-rating-icon]][sonar-path]
 
-#### Supported Telegram Bot API v4.6 (January 23, 2020 update)
+#### Supported Telegram Bot API v4.8 (April 24, 2020)
 
 ## Installation
 
@@ -146,7 +146,7 @@ If you discover any security related issues, please email [email protected] inst
 The MIT License (MIT). Please see [License File](LICENSE.md) for more information.
 
 [ico-php-v]: https://img.shields.io/travis/php-v/tg-bot-api/bot-api-base.svg?style=flat-square
-[ico-bot-api]: https://img.shields.io/badge/Bot%20API-4.7-blue.svg?style=flat-square
+[ico-bot-api]: https://img.shields.io/badge/Bot%20API-4.8-blue.svg?style=flat-square
 [ico-version]: https://img.shields.io/packagist/v/tg-bot-api/bot-api-base.svg?style=flat-square
 [ico-license]: https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square
 [ico-travis]: https://img.shields.io/travis/tg-bot-api/bot-api-base/master.svg?style=flat-square

src/Method/SendDiceMethod.php

@@ -25,6 +25,16 @@ class SendDiceMethod implements SendMethodAliasInterface
     use SendToChatVariablesTrait;
     use FillFromArrayTrait;
 
+    public const EMOJI_DICE = '🎲';
+    public const EMOJI_DARTS = '🎯';
+
+    /**
+     * Emoji on which the dice throw animation is based. Currently, must be one of “🎲” or “🎯”. Defauts to “🎲”.
+     *
+     * @var string|null
+     */
+    public $emoji;
+
     /**
      * @param int|string $chatId
      *
@@ -41,4 +51,30 @@ public static function create($chatId, array $data = null): SendDiceMethod
 
         return $instance;
     }
+
+    /**
+     * @param $chatId
+     *
+     * @throws BadArgumentException
+     */
+    public static function createWithDice($chatId, array $data = null): SendDiceMethod
+    {
+        $instance = static::create($chatId, $data);
+        $instance->emoji = static::EMOJI_DICE;
+
+        return $instance;
+    }
+
+    /**
+     * @param $chatId
+     *
+     * @throws BadArgumentException
+     */
+    public static function createWithDarts($chatId, array $data = null): SendDiceMethod
+    {
+        $instance = static::create($chatId, $data);
+        $instance->emoji = self::EMOJI_DARTS;
+
+        return $instance;
+    }
 }

src/Method/SendPollMethod.php

@@ -6,6 +6,7 @@
 
 use TgBotApi\BotApiBase\Exception\BadArgumentException;
 use TgBotApi\BotApiBase\Interfaces\PollTypeInterface;
+use TgBotApi\BotApiBase\Method\Interfaces\HasParseModeVariableInterface;
 use TgBotApi\BotApiBase\Method\Interfaces\SendMethodAliasInterface;
 use TgBotApi\BotApiBase\Method\Traits\FillFromArrayTrait;
 use TgBotApi\BotApiBase\Method\Traits\SendToChatVariablesTrait;
@@ -17,7 +18,7 @@
  *
  * @see https://core.telegram.org/bots/api#sendpoll
  */
-class SendPollMethod implements SendMethodAliasInterface, PollTypeInterface
+class SendPollMethod implements SendMethodAliasInterface, PollTypeInterface, HasParseModeVariableInterface
 {
     use FillFromArrayTrait;
     use SendToChatVariablesTrait;
@@ -64,6 +65,37 @@ class SendPollMethod implements SendMethodAliasInterface, PollTypeInterface
      */
     public $correctOptionId;
 
+    /**
+     * 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 with at most 2 line feeds after entities parsing.
+     *
+     * @var string|null
+     */
+    public $explanation;
+
+    /**
+     * Optional. Mode for parsing entities in the explanation. See formatting options for more details.
+     *
+     * @var string|null
+     */
+    public $explanationParseMode;
+
+    /**
+     * Optional. Amount of time in seconds the poll will be active after creation, 5-600.
+     * Can't be used together with close_date.
+     *
+     * @var int|null
+     */
+    public $openPeriod;
+
+    /**
+     * Point in time (will be transformed to Unix timestamp on send) when the poll will be automatically closed.
+     * Must be at least 5 and no more than 600 seconds in the future. Can't be used together with open_period.
+     *
+     * @var \DateTimeInterface|null
+     */
+    public $closeDate;
+
     /**
      * Optional. Pass True, if the poll needs to be immediately closed.
      *

src/Type/DiceType.php

@@ -7,7 +7,7 @@
 /**
  * Class DiceType.
  *
- * This object represents a dice with random value from 1 to 6.
+ * This object represents a dice with random value from 1 to 6 for currently supported base emoji.
  * (Yes, we're aware of the “proper” singular of die.
  * But it's awkward, and we decided to help it change.
  * One dice at a time!)
@@ -22,4 +22,11 @@ class DiceType
      * Value of the dice, 1-6
      */
     public $value;
+
+    /**
+     * Emoji on which the dice throw animation is based.
+     *
+     * @var string|null
+     */
+    public $emoji;
 }

src/Type/PollType.php

@@ -78,4 +78,33 @@ class PollType implements PollTypeInterface
      * @var int|null
      */
     public $correctOptionId;
+
+    /**
+     * 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.
+     *
+     * @var string|null
+     */
+    public $explanation;
+
+    /**
+     * Optional. Special entities like usernames, URLs, bot commands, etc. that appear in the explanation.
+     *
+     * @var MessageEntityType|null
+     */
+    public $explanationEntities;
+
+    /**
+     * Optional. Amount of time in seconds the poll will be active after creation.
+     *
+     * @var int|null
+     */
+    public $openPeriod;
+
+    /**
+     * Optional. Point in time (Unix timestamp) when the poll will be automatically closed.
+     *
+     * @var \DateTimeInterface|null
+     */
+    public $closeDate;
 }

tests/Method/SendDiceMethodTest.php

@@ -5,7 +5,6 @@
 namespace TgBotApi\BotApiBase\Tests\Method;
 
 use TgBotApi\BotApiBase\BotApiComplete;
-use TgBotApi\BotApiBase\Method\SendContactMethod;
 use TgBotApi\BotApiBase\Method\SendDiceMethod;
 use TgBotApi\BotApiBase\Tests\Method\Traits\InlineKeyboardMarkupTrait;
 
@@ -14,39 +13,56 @@ class SendDiceMethodTest extends MethodTestCase
     use InlineKeyboardMarkupTrait;
 
     /**
-     * @throws \TgBotApi\BotApiBase\Exception\BadArgumentException
+     * @dataProvider dataProvider
+     *
      * @throws \TgBotApi\BotApiBase\Exception\ResponseException
      */
-    public function testEncode()
+    public function testEncode(BotApiComplete $bot, SendDiceMethod $method): void
     {
-        $this->getApi()->sendDice($this->getMethod());
-        $this->getApi()->send($this->getMethod());
+        $bot->sendDice($method);
     }
 
-    private function getApi(): BotApiComplete
+    /**
+     * @throws \TgBotApi\BotApiBase\Exception\BadArgumentException
+     *
+     * @return array[]
+     */
+    public function dataProvider(): array
+    {
+        return [
+            [
+                $this->getApi(SendDiceMethod::EMOJI_DICE),
+                SendDiceMethod::createWithDice(
+                    'chat_id',
+                    [
+                        'disableNotification' => true,
+                        'replyToMessageId' => 1,
+                        'replyMarkup' => $this->buildInlineMarkupObject(),
+                    ]
+                ),
+            ],
+            [
+                $this->getApi(SendDiceMethod::EMOJI_DARTS),
+                SendDiceMethod::createWithDarts(
+                    'chat_id',
+                    [
+                        'disableNotification' => true,
+                        'replyToMessageId' => 1,
+                        'replyMarkup' => $this->buildInlineMarkupObject(),
+                    ]
+                ),
+            ],
+        ];
+    }
+
+    private function getApi(string $emoji): BotApiComplete
     {
         return $this->getBot('sendDice', [
             'chat_id' => 'chat_id',
             'disable_notification' => true,
             'reply_to_message_id' => 1,
+            'emoji' => $emoji,
             'reply_markup' => $this->buildInlineMarkupArray(),
         ], [], ['reply_markup']);
     }
-
-    /**
-     * @throws \TgBotApi\BotApiBase\Exception\BadArgumentException
-     *
-     * @return SendContactMethod
-     */
-    private function getMethod(): SendDiceMethod
-    {
-        return SendDiceMethod::create(
-            'chat_id',
-            [
-                'disableNotification' => true,
-                'replyToMessageId' => 1,
-                'replyMarkup' => $this->buildInlineMarkupObject(),
-            ]
-        );
-    }
 }