Merge pull request #5 from devrabie/feature/telegram-api-7.3-support

devrabie · web-flow · commit fc28e3eb43b8 · 2025-07-05T03:00:39.000+03:00
Add support for Telegram Bot API 7.3
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,24 +7,53 @@ Exclamation symbols (:exclamation:) note something of importance e.g. breaking c
 ### Notes
 - [:ledger: View file changes][Unreleased]
 ### Added
-- Bot API 7.2 support. This includes:
-    - Business Account Integration (New entities: `BusinessConnection`, `BusinessMessagesDeleted`; Updated `Update.php`, `Request.php`, `Message.php`)
-    - Business Information Entities (New entities: `BusinessIntro`, `BusinessLocation`, `BusinessOpeningHours`, `BusinessOpeningHoursInterval`; Updated `Chat.php`)
-    - Sticker Pack Modifications (Updated `StickerSet.php`, `InputSticker.php`, `Request.php`)
-    - Request & Shared Object Improvements (New entity: `SharedUser`; Updated `KeyboardButtonRequestUsers.php`, `KeyboardButtonRequestChat.php`, `UsersShared.php`, `ChatShared.php`)
-    - Miscellaneous Changes (New entity: `Birthdate`; Updated `Chat.php`, `Message.php`, `User.php`)
 ### Changed
 ### Deprecated
 ### Removed
 ### Fixed
 ### Security
 
+## [1.0.3] - 2024-05-07
+### Notes
+- [:ledger: View file changes][1.0.3]
+- Support for Telegram Bot API 7.3.
+### Added
+- **Poll Enhancements:**
+    - New entity `InputPollOption` (`src/Entities/Poll/InputPollOption.php`) with properties `text` and optional `text_entities`.
+    - Added optional property `question_entities` (array of `MessageEntity`) to `src/Entities/Poll.php`.
+    - Added optional property `text_entities` (array of `MessageEntity`) to `src/Entities/PollOption.php`.
+    - Updated `sendPoll` method in `src/Request.php`:
+        - Changed `options` parameter to be an array of `InputPollOption`.
+        - Added optional parameters `question_parse_mode` (string) and `question_entities` (array of `MessageEntity`).
+- **Chat and getChat Method Refactoring:**
+    - New entity `ChatFullInfo` (`src/Entities/ChatFullInfo.php`) containing all properties from `Chat` entity plus properties from `getChat` (e.g., `description`, `invite_link`, `pinned_message`, `bio`) and new optional property `max_reaction_count` (integer).
+    - Updated `getChat` method in `src/Request.php` docblock to return a `ServerResponse` with a `ChatFullInfo` object.
+- **Miscellaneous Updates:**
+    - New Chat Background entities:
+        - `src/Entities/ChatBackground.php`
+        - `src/Entities/Background/BackgroundType.php`
+        - `src/Entities/Background/BackgroundFill.php`
+    - Added optional property `chat_background_set` (`ChatBackground`) to `src/Entities/Message.php`.
+    - Added optional property `via_join_request` (boolean) to `src/Entities/ChatMemberUpdated.php`.
+    - Added optional parameter `live_period` (integer) to `editMessageLiveLocation` method in `src/Request.php`.
+### Changed
+- Version bumped to 1.0.3.
+### Deprecated
+### Removed
+### Fixed
+### Security
+
 ## [1.0.2] - 2025-07-04
 ### Notes
 - [:ledger: View file changes][1.0.2]
 - Support for Telegram Bot API 7.2.
 ### Added
-- All features from Telegram Bot API 7.2 update (see Unreleased section above for details).
+- Bot API 7.2 support. This includes:
+    - Business Account Integration (New entities: `BusinessConnection`, `BusinessMessagesDeleted`; Updated `Update.php`, `Request.php`, `Message.php`)
+    - Business Information Entities (New entities: `BusinessIntro`, `BusinessLocation`, `BusinessOpeningHours`, `BusinessOpeningHoursInterval`; Updated `Chat.php`)
+    - Sticker Pack Modifications (Updated `StickerSet.php`, `InputSticker.php`, `Request.php`)
+    - Request & Shared Object Improvements (New entity: `SharedUser`; Updated `KeyboardButtonRequestUsers.php`, `KeyboardButtonRequestChat.php`, `UsersShared.php`, `ChatShared.php`)
+    - Miscellaneous Changes (New entity: `Birthdate`; Updated `Chat.php`, `Message.php`, `User.php`)
 ### Changed
 - Version bumped to 1.0.2.
 ### Deprecated
@@ -713,7 +742,8 @@ Exclamation symbols (:exclamation:) note something of importance e.g. breaking c
 [PSR-3]: https://www.php-fig.org/psr/psr-3
 [Tidelift]: https://tidelift.com/subscription/pkg/packagist-longman-telegram-bot?utm_source=packagist-longman-telegram-bot&utm_medium=referral&utm_campaign=changelog
 
-[Unreleased]: https://github.com/php-telegram-bot/core/compare/1.0.2...develop
+[Unreleased]: https://github.com/php-telegram-bot/core/compare/1.0.3...develop
+[1.0.3]: https://github.com/php-telegram-bot/core/compare/1.0.2...1.0.3
 [1.0.2]: https://github.com/php-telegram-bot/core/compare/0.83.0...1.0.2
 [0.83.0]: https://github.com/php-telegram-bot/core/compare/0.82.0...0.83.0
 [0.82.0]: https://github.com/php-telegram-bot/core/compare/0.81.0...0.82.0
diff --git a/src/Entities/Background/BackgroundFill.php b/src/Entities/Background/BackgroundFill.php
@@ -0,0 +1,36 @@
+<?php
+
+/**
+ * This file is part of the TelegramBot package.
+ *
+ * (c) Avtandil Kikabidze aka LONGMAN <akalongman@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Longman\TelegramBot\Entities\Background;
+
+/**
+ * Class BackgroundFill
+ *
+ * The background is automatically filled based on the selected colors.
+ *
+ * @link https://core.telegram.org/bots/api#backgroundfill
+ *
+ * @method string getType()          Type of the fill, always “fill”
+ * @method int    getTopColor()      The color of the top gradient fill as a RGB24 value
+ * @method int    getBottomColor()   The color of the bottom gradient fill as a RGB24 value
+ * @method int    getRotationAngle() Clockwise rotation angle of the background fill in degrees; 0-359
+ */
+class BackgroundFill extends BackgroundType
+{
+    /**
+     * {@inheritdoc}
+     */
+    public function __construct(array $data = [])
+    {
+        $data['type'] = 'fill';
+        parent::__construct($data);
+    }
+}
diff --git a/src/Entities/Background/BackgroundType.php b/src/Entities/Background/BackgroundType.php
@@ -0,0 +1,34 @@
+<?php
+
+/**
+ * This file is part of the TelegramBot package.
+ *
+ * (c) Avtandil Kikabidze aka LONGMAN <akalongman@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Longman\TelegramBot\Entities\Background;
+
+use Longman\TelegramBot\Entities\Entity;
+
+/**
+ * Class BackgroundType
+ *
+ * This object represents the type of a background. Currently, it can be one of
+ * - BackgroundTypeFill
+ * - BackgroundTypeWallpaper
+ * - BackgroundTypePattern
+ * - BackgroundTypeChatTheme
+ *
+ * @link https://core.telegram.org/bots/api#backgroundtype
+ *
+ * @method string getType() Type of the background
+ */
+class BackgroundType extends Entity
+{
+    // Further specific properties depend on the actual type of background,
+    // which will be handled by subclasses or by checking the 'type' field.
+    // For example, BackgroundTypeFill, BackgroundTypeWallpaper, etc.
+}
diff --git a/src/Entities/ChatBackground.php b/src/Entities/ChatBackground.php
@@ -0,0 +1,36 @@
+<?php
+
+/**
+ * This file is part of the TelegramBot package.
+ *
+ * (c) Avtandil Kikabidze aka LONGMAN <akalongman@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Longman\TelegramBot\Entities;
+
+use Longman\TelegramBot\Entities\Background\BackgroundType;
+
+/**
+ * Class ChatBackground
+ *
+ * This object represents a chat background.
+ *
+ * @link https://core.telegram.org/bots/api#chatbackground
+ *
+ * @method BackgroundType getType() Type of the background
+ */
+class ChatBackground extends Entity
+{
+    /**
+     * {@inheritdoc}
+     */
+    protected function subEntities(): array
+    {
+        return [
+            'type' => BackgroundType::class,
+        ];
+    }
+}
diff --git a/src/Entities/ChatFullInfo.php b/src/Entities/ChatFullInfo.php
@@ -0,0 +1,54 @@
+<?php
+
+/**
+ * This file is part of the TelegramBot package.
+ *
+ * (c) Avtandil Kikabidze aka LONGMAN <akalongman@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Longman\TelegramBot\Entities;
+
+/**
+ * Class ChatFullInfo
+ *
+ * This object contains full information about a chat.
+ *
+ * @link https://core.telegram.org/bots/api#chatfullinfo
+ *
+ * @method string          getDescription()                        Optional. Description, for groups, supergroups and channel chats.
+ * @method string          getInviteLink()                         Optional. Primary invite link, for groups, supergroups and channel chats. Returned only in getChat.
+ * @method Message         getPinnedMessage()                      Optional. The most recent pinned message (by sending date). Returned only in getChat.
+ * @method ChatPermissions getPermissions()                        Optional. Default chat member permissions, for groups and supergroups. Returned only in getChat.
+ * @method int             getSlowModeDelay()                      Optional. For supergroups, the minimum allowed delay between consecutive messages sent by each unprivileged user; in seconds. Returned only in getChat.
+ * @method int             getUnrestrictBoostCount()               Optional. For supergroups, the minimum number of boosts that a non-administrator user needs to add in order to ignore slow mode and chat permissions.
+ * @method int             getMessageAutoDeleteTime()              Optional. The time after which all messages sent to the chat will be automatically deleted; in seconds. Returned only in getChat.
+ * @method bool            getHasAggressiveAntiSpamEnabled()       Optional. True, if aggressive anti-spam checks are enabled in the supergroup. The field is only available to chat administrators.
+ * @method bool            getHasHiddenMembers()                   Optional. True, if non-administrators can only get the list of bots and administrators in the chat. Returned only in getChat.
+ * @method bool            getHasProtectedContent()                Optional. True, if messages from the chat can't be forwarded to other chats. Returned only in getChat.
+ * @method bool            getHasVisibleHistory()                  Optional. True, if new chat members will have access to old messages; available only to chat administrators.
+ * @method string          getStickerSetName()                     Optional. For supergroups, name of group sticker set. Returned only in getChat.
+ * @method bool            getCanSetStickerSet()                   Optional. True, if the bot can change the group sticker set. Returned only in getChat.
+ * @method string          getCustomEmojiStickerSetName()          Optional. For supergroups, the name of the group's custom emoji sticker set. Custom emoji from this set can be used by all users and bots in the group.
+ * @method int             getLinkedChatId()                       Optional. Unique identifier for the linked chat, i.e. the discussion group identifier for a channel and vice versa; for supergroups and channel chats. Returned only in getChat.
+ * @method ChatLocation    getLocation()                           Optional. For supergroups, the location to which the supergroup is connected. Returned only in getChat.
+ * @method int             getMaxReactionCount()                   Optional. The maximum number of reactions that can be set on a message in the chat
+ */
+class ChatFullInfo extends Chat
+{
+    /**
+     * {@inheritdoc}
+     */
+    protected function subEntities(): array
+    {
+        return array_merge(parent::subEntities(), [
+            // Properties already defined in Chat.php and handled by its subEntities are inherited.
+            // Add or override here if ChatFullInfo has different types or new sub-entities.
+            // For example, if PinnedMessage in ChatFullInfo could be a different class than in Chat,
+            // or if new properties in ChatFullInfo are entities themselves.
+            // Based on the current structure, most of these are already covered by Chat.php
+        ]);
+    }
+}
diff --git a/src/Entities/ChatMemberUpdated.php b/src/Entities/ChatMemberUpdated.php
@@ -28,6 +28,7 @@
  * @method ChatMember      getNewChatMember()     New information about the chat member
  * @method ChatInviteLink  getInviteLink()        Optional. Chat invite link, which was used by the user to join the chat; for joining by invite link events only.
  * @method bool            getViaChatFolderInviteLink() Optional. True, if the user joined the chat via a chat folder invite link
+ * @method bool            getViaJoinRequest()    Optional. True, if the user joined the chat after sending a direct join request without using an invite link and being approved by an administrator
  */
 class ChatMemberUpdated extends Entity
 {
diff --git a/src/Entities/Message.php b/src/Entities/Message.php
@@ -116,6 +116,7 @@
  * @method string                                 getBusinessConnectionId()                   Optional. Unique identifier of the business connection from which the message was received. If non-empty, the message is business_message.
  * @method User                                   getSenderBusinessBot()                      Optional. The bot that actually sent the message on behalf of the business account. Available only for outgoing messages sent on behalf of the business account.
  * @method bool                                   getIsFromOffline()                          Optional. True, if the message was sent by an offline user. Applicable to messages sent by the bot on behalf of a user to a fellow user in a private chat.
+ * @method ChatBackground                         getChatBackgroundSet()                      Optional. Service message: chat background set
  */
 class Message extends Entity implements MaybeInaccessibleMessage
 {
@@ -181,6 +182,7 @@ protected function subEntities(): array
             'video_chat_participants_invited'   => VideoChatParticipantsInvited::class,
             'web_app_data'                      => WebAppData::class,
             'reply_markup'                      => InlineKeyboard::class,
+            'chat_background_set'               => ChatBackground::class,
         ];
     }
 
@@ -328,6 +330,7 @@ public function getType(): string
             'video_chat_participants_invited',
             'web_app_data',
             'reply_markup',
+            'chat_background_set',
         ];
 
         $is_command = $this->getCommand() !== null;
diff --git a/src/Entities/Poll.php b/src/Entities/Poll.php
@@ -31,6 +31,7 @@
  * @method MessageEntity[] getExplanationEntities()   Optional. Special entities like usernames, URLs, bot commands, etc. that appear in the explanation
  * @method int             getOpenPeriod()            Optional. Amount of time in seconds the poll will be active after creation
  * @method int             getCloseDate()             Optional. Point in time (Unix timestamp) when the poll will be automatically closed
+ * @method MessageEntity[] getQuestionEntities()      Optional. Special entities that appear in the question. Currently, only custom emoji entities are allowed in poll questions
  */
 class Poll extends Entity
 {
@@ -42,6 +43,7 @@ protected function subEntities(): array
         return [
             'options'              => [PollOption::class],
             'explanation_entities' => [MessageEntity::class],
+            'question_entities'    => [MessageEntity::class],
         ];
     }
 }
diff --git a/src/Entities/Poll/InputPollOption.php b/src/Entities/Poll/InputPollOption.php
@@ -0,0 +1,38 @@
+<?php
+
+/**
+ * This file is part of the TelegramBot package.
+ *
+ * (c) Avtandil Kikabidze aka LONGMAN <akalongman@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Longman\TelegramBot\Entities\Poll;
+
+use Longman\TelegramBot\Entities\Entity;
+use Longman\TelegramBot\Entities\MessageEntity;
+
+/**
+ * Class InputPollOption
+ *
+ * This entity contains information about one answer option in a poll to be sent.
+ *
+ * @link https://core.telegram.org/bots/api#inputpolloption
+ *
+ * @method string          getText()                 Option text, 1-100 characters
+ * @method MessageEntity[] getTextEntities()         Optional. A JSON-serialized list of special entities that appear in the poll option text. It can be specified instead of text_parse_mode
+ */
+class InputPollOption extends Entity
+{
+    /**
+     * {@inheritdoc}
+     */
+    protected function subEntities(): array
+    {
+        return [
+            'text_entities' => [MessageEntity::class],
+        ];
+    }
+}
diff --git a/src/Entities/PollOption.php b/src/Entities/PollOption.php
@@ -18,10 +18,19 @@
  *
  * @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
+ * @method string          getText()          Option text, 1-100 characters
+ * @method int             getVoterCount()    Number of users that voted for this option
+ * @method MessageEntity[] getTextEntities()  Optional. Special entities that appear in the option text. Currently, only custom emoji entities are allowed in poll option texts
  */
 class PollOption extends Entity
 {
-
+    /**
+     * {@inheritdoc}
+     */
+    protected function subEntities(): array
+    {
+        return [
+            'text_entities' => [MessageEntity::class],
+        ];
+    }
 }
diff --git a/src/Request.php b/src/Request.php
diff --git a/src/Telegram.php b/src/Telegram.php

Original file line number	Diff line number	Diff line change
`@@ -28,6 +28,7 @@`
`28`	`28`	`* @method ChatMember getNewChatMember() New information about the chat member`
`29`	`29`	`* @method ChatInviteLink getInviteLink() Optional. Chat invite link, which was used by the user to join the chat; for joining by invite link events only.`
`30`	`30`	`* @method bool getViaChatFolderInviteLink() Optional. True, if the user joined the chat via a chat folder invite link`
	`31`	`+ * @method bool getViaJoinRequest() Optional. True, if the user joined the chat after sending a direct join request without using an invite link and being approved by an administrator`
`31`	`32`	`*/`
`32`	`33`	`class ChatMemberUpdated extends Entity`
`33`	`34`	`{`
Original file line number	Diff line number	Diff line change
`@@ -31,6 +31,7 @@`
`31`	`31`	`* @method MessageEntity[] getExplanationEntities() Optional. Special entities like usernames, URLs, bot commands, etc. that appear in the explanation`
`32`	`32`	`* @method int getOpenPeriod() Optional. Amount of time in seconds the poll will be active after creation`
`33`	`33`	`* @method int getCloseDate() Optional. Point in time (Unix timestamp) when the poll will be automatically closed`
	`34`	`+ * @method MessageEntity[] getQuestionEntities() Optional. Special entities that appear in the question. Currently, only custom emoji entities are allowed in poll questions`
`34`	`35`	`*/`
`35`	`36`	`class Poll extends Entity`
`36`	`37`	`{`
`@@ -42,6 +43,7 @@ protected function subEntities(): array`
`42`	`43`	`return [`
`43`	`44`	`'options' => [PollOption::class],`
`44`	`45`	`'explanation_entities' => [MessageEntity::class],`
	`46`	`+ 'question_entities' => [MessageEntity::class],`
`45`	`47`	`];`
`46`	`48`	`}`
`47`	`49`	`}`
Original file line number	Diff line number	Diff line change
`@@ -18,10 +18,19 @@`
`18`	`18`	`*`
`19`	`19`	`* @link https://core.telegram.org/bots/api#polloption`
`20`	`20`	`*`
`21`		`- * @method string getText() Option text, 1-100 characters`
`22`		`- * @method int getVoterCount() Number of users that voted for this option`
	`21`	`+ * @method string getText() Option text, 1-100 characters`
	`22`	`+ * @method int getVoterCount() Number of users that voted for this option`
	`23`	`+ * @method MessageEntity[] getTextEntities() Optional. Special entities that appear in the option text. Currently, only custom emoji entities are allowed in poll option texts`
`23`	`24`	`*/`
`24`	`25`	`class PollOption extends Entity`
`25`	`26`	`{`
`26`		`-`
	`27`	`+ /**`
	`28`	`+ * {@inheritdoc}`
	`29`	`+ */`
	`30`	`+ protected function subEntities(): array`
	`31`	`+ {`
	`32`	`+ return [`
	`33`	`+ 'text_entities' => [MessageEntity::class],`
	`34`	`+ ];`
	`35`	`+ }`
`27`	`36`	`}`