Support attach://<file_attach_name> and rename thumb to thumbnail

TelegramBot · May 29, 2023 · 3d92cfe · 3d92cfe
1 parent 82e7e7f
commit 3d92cfe
Show file tree

Hide file tree

Showing 22 changed files with 728 additions and 190 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,13 @@ 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
+
+### Deprecated
+- Deprecate using `thumb*` methods in `\TelegramBot\Api\BotApi`
+- Deprecate method `\TelegramBot\Api\BotApi::setStickerSetThumb`. Use `\TelegramBot\Api\BotApi::setStickerSetThumbnail` instead
 
 ## 2.4.0 - 2023-05-11
 

diff --git a/src/BotApi.php b/src/BotApi.php
@@ -915,6 +915,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
@@ -932,7 +933,8 @@ public function createNewStickerSet(
         $tgsSticker = null,
         $webmSticker = null,
         $stickerType = null,
-        $maskPosition = null
+        $maskPosition = null,
+        $attachments = []
     ) {
         return $this->call('createNewStickerSet', [
             'user_id' => $userId,
@@ -944,7 +946,7 @@ public function createNewStickerSet(
             'sticker_type' => $stickerType,
             'emojis' => $emojis,
             'mask_position' => is_null($maskPosition) ? $maskPosition : $maskPosition->toJson(),
-        ]);
+        ] + $attachments);
     }
 
     /**
@@ -961,6 +963,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
@@ -973,7 +977,8 @@ public function addStickerToSet(
         $pngSticker,
         $tgsSticker = null,
         $webmSticker = null,
-        $maskPosition = null
+        $maskPosition = null,
+        $attachments = []
     ) {
         return $this->call('addStickerToSet', [
             'user_id' => $userId,
@@ -983,7 +988,7 @@ public function addStickerToSet(
             'webm_sticker' => $webmSticker,
             'emojis' => $emojis,
             'mask_position' => is_null($maskPosition) ? $maskPosition : $maskPosition->toJson(),
-        ]);
+        ] + $attachments);
     }
 
     /**
@@ -1012,24 +1017,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).
@@ -1047,6 +1074,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
@@ -1064,7 +1092,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,
@@ -1079,6 +1108,7 @@ public function sendVideo(
             'parse_mode' => $parseMode,
             'protect_content' => (bool) $protectContent,
             'allow_sending_without_reply' => (bool) $allowSendingWithoutReply,
+            'thumbnail' => $thumbnail,
         ]));
     }
 
@@ -1098,6 +1128,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
@@ -1114,7 +1145,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,
@@ -1128,6 +1160,7 @@ public function sendAnimation(
             'parse_mode' => $parseMode,
             'protect_content' => (bool) $protectContent,
             'allow_sending_without_reply' => (bool) $allowSendingWithoutReply,
+            'thumbnail' => $thumbnail,
         ]));
     }
 
@@ -1241,6 +1274,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
@@ -1261,7 +1295,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,
@@ -1275,6 +1310,7 @@ public function sendAudio(
             'parse_mode' => $parseMode,
             'protect_content' => (bool) $protectContent,
             'allow_sending_without_reply' => (bool) $allowSendingWithoutReply,
+            'thumbnail' => $thumbnail,
         ]));
     }
 
@@ -1336,6 +1372,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
@@ -1351,7 +1388,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,
@@ -1364,6 +1402,7 @@ public function sendDocument(
             'parse_mode' => $parseMode,
             'protect_content' => (bool) $protectContent,
             'allow_sending_without_reply' => (bool) $allowSendingWithoutReply,
+            'thumbnail' => $thumbnail,
         ]));
     }
 
@@ -1660,6 +1699,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
@@ -1671,15 +1712,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;
         }
@@ -2273,6 +2315,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
@@ -2288,7 +2331,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,
@@ -2301,6 +2345,7 @@ public function sendVideoNote(
             'disable_notification' => (bool) $disableNotification,
             'protect_content' => (bool) $protectContent,
             'allow_sending_without_reply' => (bool) $allowSendingWithoutReply,
+            'thumbnail' => $thumbnail,
         ]));
     }
 
@@ -2315,6 +2360,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
@@ -2326,7 +2372,8 @@ public function sendMediaGroup(
         $replyToMessageId = null,
         $messageThreadId = null,
         $protectContent = null,
-        $allowSendingWithoutReply = null
+        $allowSendingWithoutReply = null,
+        $attachments = []
     ) {
         return ArrayOfMessages::fromResponse($this->call('sendMediaGroup', [
             'chat_id' => $chatId,
@@ -2336,7 +2383,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);
     }
 
     /**