Merge pull request #433 from BoShurik/attachments

Support `attach://<file_attach_name>` and rename `thumb` to `thumbnail`
TelegramBot · Jun 27, 2023 · a829ef4 · a829ef4
2 parents e5cded2 + e538b55
commit a829ef4
Show file tree

Hide file tree

Showing 22 changed files with 727 additions and 191 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,9 +6,14 @@ All Notable changes to `PHP Telegram Bot Api` will be documented in this file
 
 ### Added
 - Add missing `protect_content` and `allow_sending_without_reply` parameters to `\TelegramBot\Api\BotApi` methods
+- Add support `attach://<file_attach_name>` in `\TelegramBot\Api\BotApi` methods `sendMediaGroup`, `createNewStickerSet`, `addStickerToSet`, `editMessageMedia`
+- Rename `thumb` to `thumbnail` parameter in `Animation`, `Document`, `Sticker`, `StickerSet`, `Video`, `VideoNote` types
+- Rename `thumb_*` to `thumbnail_*` parameter in `Inline/QueryResult` types
 - Add missing phpDoc for `$replyMarkup` parameters
-
+- 
 ### Deprecated
+- Deprecate using `thumb*` methods in `\TelegramBot\Api\BotApi`
+- Deprecate method `\TelegramBot\Api\BotApi::setStickerSetThumb`. Use `\TelegramBot\Api\BotApi::setStickerSetThumbnail` instead
 - Deprecate `\TelegramBot\Api\Types\ReplyKeyboardHide` class
 
 ## 2.4.0 - 2023-05-11

diff --git a/src/BotApi.php b/src/BotApi.php
@@ -914,6 +914,7 @@ public function uploadStickerFile($userId, $pngSticker)
      * @param string $stickerType Sticker type, one of “png”, “tgs”, or “webp”
      * @param string $emojis One or more emoji corresponding to the sticker
      * @param MaskPosition|null $maskPosition A JSON-serialized object for position where the mask should be placed on faces
+     * @param array<string, \CURLFile|\CURLStringFile> $attachments Attachments to use in attach://<attachment>
      *
      * @throws InvalidArgumentException
      * @throws Exception
@@ -931,7 +932,8 @@ public function createNewStickerSet(
         $tgsSticker = null,
         $webmSticker = null,
         $stickerType = null,
-        $maskPosition = null
+        $maskPosition = null,
+        $attachments = []
     ) {
         return $this->call('createNewStickerSet', [
             'user_id' => $userId,
@@ -943,7 +945,7 @@ public function createNewStickerSet(
             'sticker_type' => $stickerType,
             'emojis' => $emojis,
             'mask_position' => is_null($maskPosition) ? $maskPosition : $maskPosition->toJson(),
-        ]);
+        ] + $attachments);
     }
 
     /**
@@ -960,6 +962,8 @@ public function createNewStickerSet(
      * @param string|null $tgsSticker
      * @param string|null $webmSticker
      * @param MaskPosition|null $maskPosition
+     * @param array<string, \CURLFile|\CURLStringFile> $attachments Attachments to use in attach://<attachment>
+     *
      * @return bool
      * @throws Exception
      * @throws HttpException
@@ -972,7 +976,8 @@ public function addStickerToSet(
         $pngSticker,
         $tgsSticker = null,
         $webmSticker = null,
-        $maskPosition = null
+        $maskPosition = null,
+        $attachments = []
     ) {
         return $this->call('addStickerToSet', [
             'user_id' => $userId,
@@ -982,7 +987,7 @@ public function addStickerToSet(
             'webm_sticker' => $webmSticker,
             'emojis' => $emojis,
             'mask_position' => is_null($maskPosition) ? $maskPosition : $maskPosition->toJson(),
-        ]);
+        ] + $attachments);
     }
 
     /**
@@ -1011,24 +1016,46 @@ public function setStickerPositionInSet($sticker, $position)
      *
      * @param string $name Sticker set name
      * @param string $userId User identifier of sticker set owner
-     * @param File|null $thumb A PNG image with the thumbnail,
-     *                         must be up to 128 kilobytes in size and have width and height exactly 100px,
-     *                         or a TGS animation with the thumbnail up to 32 kilobytes in size
+     * @param File|null $thumbnail A PNG image with the thumbnail,
+     *                             must be up to 128 kilobytes in size and have width and height exactly 100px,
+     *                             or a TGS animation with the thumbnail up to 32 kilobytes in size
      *
      * @return bool
      *
      * @throws InvalidArgumentException
      * @throws Exception
      */
-    public function setStickerSetThumb($name, $userId, $thumb = null)
+    public function setStickerSetThumbnail($name, $userId, $thumbnail = null)
     {
         return $this->call('setStickerSetThumb', [
             'name' => $name,
             'user_id' => $userId,
-            'thumb' => $thumb,
+            'thumbnail' => $thumbnail,
         ]);
     }
 
+    /**
+     * @deprecated Use setStickerSetThumbnail
+     *
+     * Use this method to delete a sticker from a set created by the bot.
+     * Returns True on success.
+     *
+     * @param string $name Sticker set name
+     * @param string $userId User identifier of sticker set owner
+     * @param File|null $thumb A PNG image with the thumbnail,
+     *                         must be up to 128 kilobytes in size and have width and height exactly 100px,
+     *                         or a TGS animation with the thumbnail up to 32 kilobytes in size
+     *
+     * @return bool
+     *
+     * @throws InvalidArgumentException
+     * @throws Exception
+     */
+    public function setStickerSetThumb($name, $userId, $thumb = null)
+    {
+        return $this->setStickerSetThumbnail($name, $userId, $thumb);
+    }
+
     /**
      * Use this method to send video files,
      * Telegram clients support mp4 videos (other formats may be sent as Document).
@@ -1046,6 +1073,7 @@ public function setStickerSetThumb($name, $userId, $thumb = null)
      * @param int|null $messageThreadId
      * @param bool|null $protectContent
      * @param bool|null $allowSendingWithoutReply
+     * @param \CURLFile|\CURLStringFile|string|null $thumbnail
      *
      * @return Message
      * @throws InvalidArgumentException
@@ -1063,7 +1091,8 @@ public function sendVideo(
         $parseMode = null,
         $messageThreadId = null,
         $protectContent = null,
-        $allowSendingWithoutReply = null
+        $allowSendingWithoutReply = null,
+        $thumbnail = null
     ) {
         return Message::fromResponse($this->call('sendVideo', [
             'chat_id' => $chatId,
@@ -1078,6 +1107,7 @@ public function sendVideo(
             'parse_mode' => $parseMode,
             'protect_content' => (bool) $protectContent,
             'allow_sending_without_reply' => (bool) $allowSendingWithoutReply,
+            'thumbnail' => $thumbnail,
         ]));
     }
 
@@ -1097,6 +1127,7 @@ public function sendVideo(
      * @param int|null $messageThreadId
      * @param bool|null $protectContent
      * @param bool|null $allowSendingWithoutReply
+     * @param \CURLFile|\CURLStringFile|string|null $thumbnail
      *
      * @return Message
      * @throws InvalidArgumentException
@@ -1113,7 +1144,8 @@ public function sendAnimation(
         $parseMode = null,
         $messageThreadId = null,
         $protectContent = null,
-        $allowSendingWithoutReply = null
+        $allowSendingWithoutReply = null,
+        $thumbnail = null
     ) {
         return Message::fromResponse($this->call('sendAnimation', [
             'chat_id' => $chatId,
@@ -1127,6 +1159,7 @@ public function sendAnimation(
             'parse_mode' => $parseMode,
             'protect_content' => (bool) $protectContent,
             'allow_sending_without_reply' => (bool) $allowSendingWithoutReply,
+            'thumbnail' => $thumbnail,
         ]));
     }
 
@@ -1240,6 +1273,7 @@ public function forwardMessage(
      * @param string|null $parseMode
      * @param bool|null $protectContent
      * @param bool|null $allowSendingWithoutReply
+     * @param \CURLFile|\CURLStringFile|string|null $thumbnail
      *
      * @return Message
      * @throws InvalidArgumentException
@@ -1260,7 +1294,8 @@ public function sendAudio(
         $disableNotification = false,
         $parseMode = null,
         $protectContent = null,
-        $allowSendingWithoutReply = null
+        $allowSendingWithoutReply = null,
+        $thumbnail = null
     ) {
         return Message::fromResponse($this->call('sendAudio', [
             'chat_id' => $chatId,
@@ -1274,6 +1309,7 @@ public function sendAudio(
             'parse_mode' => $parseMode,
             'protect_content' => (bool) $protectContent,
             'allow_sending_without_reply' => (bool) $allowSendingWithoutReply,
+            'thumbnail' => $thumbnail,
         ]));
     }
 
@@ -1335,6 +1371,7 @@ public function sendPhoto(
      * @param int|null $messageThreadId
      * @param bool|null $protectContent
      * @param bool|null $allowSendingWithoutReply
+     * @param \CURLFile|\CURLStringFile|string|null $thumbnail
      *
      * @return Message
      * @throws InvalidArgumentException
@@ -1350,7 +1387,8 @@ public function sendDocument(
         $parseMode = null,
         $messageThreadId = null,
         $protectContent = null,
-        $allowSendingWithoutReply = null
+        $allowSendingWithoutReply = null,
+        $thumbnail = null
     ) {
         return Message::fromResponse($this->call('sendDocument', [
             'chat_id' => $chatId,
@@ -1363,6 +1401,7 @@ public function sendDocument(
             'parse_mode' => $parseMode,
             'protect_content' => (bool) $protectContent,
             'allow_sending_without_reply' => (bool) $allowSendingWithoutReply,
+            'thumbnail' => $thumbnail,
         ]));
     }
 
@@ -1659,6 +1698,8 @@ public function editMessageCaption(
      * @param InputMedia $media
      * @param string|null $inlineMessageId
      * @param InlineKeyboardMarkup|null $replyMarkup
+     * @param array<string, \CURLFile|\CURLStringFile> $attachments Attachments to use in attach://<attachment>
+     *
      * @return Message|true
      *
      * @throws Exception
@@ -1670,15 +1711,16 @@ public function editMessageMedia(
         $messageId,
         InputMedia $media,
         $inlineMessageId = null,
-        $replyMarkup = null
+        $replyMarkup = null,
+        $attachments = []
     ) {
         $response = $this->call('editMessageMedia', [
             'chat_id' => $chatId,
             'message_id' => $messageId,
             'inline_message_id' => $inlineMessageId,
             'media' => $media->toJson(),
             'reply_markup' => is_null($replyMarkup) ? $replyMarkup : $replyMarkup->toJson(),
-        ]);
+        ] + $attachments);
         if ($response === true) {
             return true;
         }
@@ -2272,6 +2314,7 @@ public function getChatAdministrators($chatId)
      * @param int|null $messageThreadId
      * @param bool|null $protectContent
      * @param bool|null $allowSendingWithoutReply
+     * @param \CURLFile|\CURLStringFile|string|null $thumbnail
      *
      * @return Message
      * @throws InvalidArgumentException
@@ -2287,7 +2330,8 @@ public function sendVideoNote(
         $disableNotification = false,
         $messageThreadId = null,
         $protectContent = null,
-        $allowSendingWithoutReply = null
+        $allowSendingWithoutReply = null,
+        $thumbnail = null
     ) {
         return Message::fromResponse($this->call('sendVideoNote', [
             'chat_id' => $chatId,
@@ -2300,6 +2344,7 @@ public function sendVideoNote(
             'disable_notification' => (bool) $disableNotification,
             'protect_content' => (bool) $protectContent,
             'allow_sending_without_reply' => (bool) $allowSendingWithoutReply,
+            'thumbnail' => $thumbnail,
         ]));
     }
 
@@ -2314,6 +2359,7 @@ public function sendVideoNote(
      * @param int|null $messageThreadId
      * @param bool|null $protectContent
      * @param bool|null $allowSendingWithoutReply
+     * @param array<string, \CURLFile|\CURLStringFile> $attachments Attachments to use in attach://<attachment>
      *
      * @return Message[]
      * @throws Exception
@@ -2325,7 +2371,8 @@ public function sendMediaGroup(
         $replyToMessageId = null,
         $messageThreadId = null,
         $protectContent = null,
-        $allowSendingWithoutReply = null
+        $allowSendingWithoutReply = null,
+        $attachments = []
     ) {
         return ArrayOfMessages::fromResponse($this->call('sendMediaGroup', [
             'chat_id' => $chatId,
@@ -2335,7 +2382,7 @@ public function sendMediaGroup(
             'disable_notification' => (bool) $disableNotification,
             'protect_content' => (bool) $protectContent,
             'allow_sending_without_reply' => (bool) $allowSendingWithoutReply,
-        ]));
+        ] + $attachments));
     }
 
     /**

diff --git a/src/Types/Animation.php b/src/Types/Animation.php
@@ -32,7 +32,7 @@ class Animation extends BaseType implements TypeInterface
         'width' => true,
         'height' => true,
         'duration' => true,
-        'thumb' => PhotoSize::class,
+        'thumbnail' => PhotoSize::class,
         'file_name' => true,
         'mime_type' => true,
         'file_size' => true
@@ -78,7 +78,7 @@ class Animation extends BaseType implements TypeInterface
      *
      * @var PhotoSize
      */
-    protected $thumb;
+    protected $thumbnail;
 
     /**
      * Optional. Animation thumbnail as defined by sender
@@ -221,18 +221,40 @@ public function setMimeType($mimeType)
     /**
      * @return PhotoSize
      */
+    public function getThumbnail()
+    {
+        return $this->thumbnail;
+    }
+
+    /**
+     * @param PhotoSize $thumbnail
+     * @return void
+     */
+    public function setThumbnail(PhotoSize $thumbnail)
+    {
+        $this->thumbnail = $thumbnail;
+    }
+
+    /**
+     * @deprecated use getThumbnail method
+     *
+     * @return PhotoSize|null
+     */
     public function getThumb()
     {
-        return $this->thumb;
+        return $this->getThumbnail();
     }
 
     /**
+     * @deprecated use setThumbnail method
+     *
      * @param PhotoSize $thumb
+     *
      * @return void
      */
-    public function setThumb(PhotoSize $thumb)
+    public function setThumb($thumb)
     {
-        $this->thumb = $thumb;
+        $this->setThumbnail($thumb);
     }
 
     /**