Merge pull request #1371 from php-telegram-bot/api-6.3

Bot API 6.3

Author: TiiFuchs

CHANGELOG.md

@@ -5,8 +5,16 @@ Exclamation symbols (:exclamation:) note something of importance e.g. breaking c
 
 ## [Unreleased]
 ### Notes
-- [:ledger: View file changes][Unreleased]
-### Added
+- [:ledger: View file changes][Unreleased] ∙ [:page_with_curl: DB migration script][0.80.0-sql-migration]
+- This update adds support for [Bot API 6.3](https://core.telegram.org/bots/api#november-5-2022) (@TiiFuchs)
+### Added
+- Added the field `is_forum` to the class `Chat`.
+- Added the fields `is_topic_message` and `message_thread_id` to the class `Message` to allow detection of messages belonging to a forum topic and their message thread identifier.
+- Added the classes `ForumTopicCreated`, `ForumTopicClosed`, and `ForumTopicReopened` and the fields `forum_topic_created`, `forum_topic_closed`, and `forum_topic_reopened` to the class `Message`.
+- Added the field `can_manage_topics` to the classes `ChatAdministratorRights`, `ChatPermissions`, `ChatMemberAdministrator`, and `ChatMemberRestricted`.
+- Added the methods `createForumTopic`, `editForumTopic`, `closeForumTopic`, `reopenForumTopic`, `deleteForumTopic`, `unpinAllForumTopicMessages`, and `getForumTopicIconStickers` for forum topic management.
+- Added support for Multiple Usernames via the field `active_usernames` in the class `Chat`.
+- Added the field `emoji_status_custom_emoji_id` to the class `Chat`.
 ### Changed
 ### Deprecated
 ### Removed
@@ -603,6 +611,7 @@ Exclamation symbols (:exclamation:) note something of importance e.g. breaking c
 ### Deprecated
 - Move `hideKeyboard` to `removeKeyboard`.
 
+[unreleased-sql-migration]: https://github.com/php-telegram-bot/core/tree/master/utils/db-schema-update/new-release.sql
 [0.78.0-sql-migration]: https://github.com/php-telegram-bot/core/tree/master/utils/db-schema-update/0.77.1-0.78.0.sql
 [0.77.0-sql-migration]: https://github.com/php-telegram-bot/core/tree/master/utils/db-schema-update/0.76.1-0.77.0.sql
 [0.75.0-sql-migration]: https://github.com/php-telegram-bot/core/tree/master/utils/db-schema-update/0.74.0-0.75.0.sql

README.md

@@ -7,7 +7,7 @@
 
 A Telegram Bot based on the official [Telegram Bot API]
 
-[![API Version](https://img.shields.io/badge/Bot%20API-6.2%20%28August%202022%29-32a2da.svg)](https://core.telegram.org/bots/api#june-20-2022)
+[![API Version](https://img.shields.io/badge/Bot%20API-6.3%20%28November%202022%29-32a2da.svg)](https://core.telegram.org/bots/api#november-5-2022)
 [![Join the bot support group on Telegram](https://img.shields.io/badge/telegram-@PHP__Telegram__Bot__Support-64659d.svg)](https://telegram.me/PHP_Telegram_Bot_Support)
 [![Donate](https://img.shields.io/badge/%F0%9F%92%99-Donate%20%2F%20Support%20Us-blue.svg)](#donate)
 
@@ -78,7 +78,7 @@ This Bot aims to provide a platform where one can simply write a bot and have in
 
 The Bot can:
 - Retrieve updates with [webhook](#webhook-installation) and [getUpdates](#getupdates-installation) methods.
-- Supports all types and methods according to Telegram Bot API 6.2 (August 2022).
+- Supports all types and methods according to Telegram Bot API 6.3 (November 2022).
 - Supports supergroups.
 - Handle commands in chat with other bots.
 - Manage Channel from the bot admin interface.
@@ -389,15 +389,15 @@ The reason for denying an update can be defined with the `$reason` parameter. Th
 
 ### Types
 
-All types are implemented according to Telegram API 6.2 (August 2022).
+All types are implemented according to Telegram API 6.3 (November 2022).
 
 ### Inline Query
 
-Full support for inline query according to Telegram API 6.2 (August 2022).
+Full support for inline query according to Telegram API 6.3 (November 2022).
 
 ### Methods
 
-All methods are implemented according to Telegram API 6.2 (August 2022).
+All methods are implemented according to Telegram API 6.3 (November 2022).
 
 #### Send Message
 

src/DB.php

@@ -493,15 +493,16 @@ public static function insertChat(Chat $chat, ?string $date = null, ?int $migrat
         try {
             $sth = self::$pdo->prepare('
                 INSERT IGNORE INTO `' . TB_CHAT . '`
-                (`id`, `type`, `title`, `username`, `first_name`, `last_name`, `created_at` ,`updated_at`, `old_id`)
+                (`id`, `type`, `title`, `username`, `first_name`, `last_name`, `is_forum`, `created_at` ,`updated_at`, `old_id`)
                 VALUES
-                (:id, :type, :title, :username, :first_name, :last_name, :created_at, :updated_at, :old_id)
+                (:id, :type, :title, :username, :first_name, :last_name, :is_forum, :created_at, :updated_at, :old_id)
                 ON DUPLICATE KEY UPDATE
                     `type`                           = VALUES(`type`),
                     `title`                          = VALUES(`title`),
                     `username`                       = VALUES(`username`),
                     `first_name`                     = VALUES(`first_name`),
                     `last_name`                      = VALUES(`last_name`),
+                    `is_forum`                       = VALUES(`is_forum`),
                     `updated_at`                     = VALUES(`updated_at`)
             ');
 
@@ -523,6 +524,7 @@ public static function insertChat(Chat $chat, ?string $date = null, ?int $migrat
             $sth->bindValue(':username', $chat->getUsername());
             $sth->bindValue(':first_name', $chat->getFirstName());
             $sth->bindValue(':last_name', $chat->getLastName());
+            $sth->bindValue(':is_forum', $chat->getIsForum());
             $date = $date ?: self::getTimestamp();
             $sth->bindValue(':created_at', $date);
             $sth->bindValue(':updated_at', $date);
@@ -1131,24 +1133,26 @@ public static function insertMessageRequest(Message $message): bool
             $sth = self::$pdo->prepare('
                 INSERT IGNORE INTO `' . TB_MESSAGE . '`
                 (
-                    `id`, `user_id`, `chat_id`, `sender_chat_id`, `date`, `forward_from`, `forward_from_chat`, `forward_from_message_id`,
-                    `forward_signature`, `forward_sender_name`, `forward_date`,
+                    `id`, `user_id`, `chat_id`, `message_thread_id`, `sender_chat_id`, `date`, `forward_from`, `forward_from_chat`, `forward_from_message_id`,
+                    `forward_signature`, `forward_sender_name`, `forward_date`, `is_topic_message`,
                     `reply_to_chat`, `reply_to_message`, `via_bot`, `edit_date`, `media_group_id`, `author_signature`, `text`, `entities`, `caption_entities`,
                     `audio`, `document`, `animation`, `game`, `photo`, `sticker`, `video`, `voice`, `video_note`, `caption`, `contact`,
                     `location`, `venue`, `poll`, `dice`, `new_chat_members`, `left_chat_member`,
                     `new_chat_title`, `new_chat_photo`, `delete_chat_photo`, `group_chat_created`,
                     `supergroup_chat_created`, `channel_chat_created`, `message_auto_delete_timer_changed`, `migrate_to_chat_id`, `migrate_from_chat_id`,
                     `pinned_message`, `invoice`, `successful_payment`, `connected_website`, `passport_data`, `proximity_alert_triggered`,
+                    `forum_topic_created`, `forum_topic_closed`, `forum_topic_reopened`,
                     `video_chat_scheduled`, `video_chat_started`, `video_chat_ended`, `video_chat_participants_invited`, `web_app_data`, `reply_markup`
                 ) VALUES (
-                    :message_id, :user_id, :chat_id, :sender_chat_id, :date, :forward_from, :forward_from_chat, :forward_from_message_id,
-                    :forward_signature, :forward_sender_name, :forward_date,
+                    :message_id, :user_id, :chat_id, :message_thread_id, :sender_chat_id, :date, :forward_from, :forward_from_chat, :forward_from_message_id,
+                    :forward_signature, :forward_sender_name, :forward_date, :is_topic_message,
                     :reply_to_chat, :reply_to_message, :via_bot, :edit_date, :media_group_id, :author_signature, :text, :entities, :caption_entities,
                     :audio, :document, :animation, :game, :photo, :sticker, :video, :voice, :video_note, :caption, :contact,
                     :location, :venue, :poll, :dice, :new_chat_members, :left_chat_member,
                     :new_chat_title, :new_chat_photo, :delete_chat_photo, :group_chat_created,
                     :supergroup_chat_created, :channel_chat_created, :message_auto_delete_timer_changed, :migrate_to_chat_id, :migrate_from_chat_id,
                     :pinned_message, :invoice, :successful_payment, :connected_website, :passport_data, :proximity_alert_triggered,
+                    :forum_topic_created, :forum_topic_closed, :forum_topic_reopened,
                     :video_chat_scheduled, :video_chat_started, :video_chat_ended, :video_chat_participants_invited, :web_app_data, :reply_markup
                 )
             ');
@@ -1167,6 +1171,7 @@ public static function insertMessageRequest(Message $message): bool
             $sth->bindValue(':message_id', $message->getMessageId());
             $sth->bindValue(':chat_id', $chat_id);
             $sth->bindValue(':sender_chat_id', $sender_chat_id);
+            $sth->bindValue(':message_thread_id', $message->getMessageThreadId());
             $sth->bindValue(':user_id', $user_id);
             $sth->bindValue(':date', $date);
             $sth->bindValue(':forward_from', $forward_from);
@@ -1175,6 +1180,7 @@ public static function insertMessageRequest(Message $message): bool
             $sth->bindValue(':forward_signature', $message->getForwardSignature());
             $sth->bindValue(':forward_sender_name', $message->getForwardSenderName());
             $sth->bindValue(':forward_date', $forward_date);
+            $sth->bindValue(':is_topic_message', $message->getIsTopicMessage());
 
             $reply_to_chat_id = null;
             if ($reply_to_message_id !== null) {
@@ -1222,6 +1228,9 @@ public static function insertMessageRequest(Message $message): bool
             $sth->bindValue(':connected_website', $message->getConnectedWebsite());
             $sth->bindValue(':passport_data', $message->getPassportData());
             $sth->bindValue(':proximity_alert_triggered', $message->getProximityAlertTriggered());
+            $sth->bindValue(':forum_topic_created', $message->getForumTopicCreated());
+            $sth->bindValue(':forum_topic_closed', $message->getForumTopicClosed());
+            $sth->bindValue(':forum_topic_reopened', $message->getForumTopicReopened());
             $sth->bindValue(':video_chat_scheduled', $message->getVideoChatScheduled());
             $sth->bindValue(':video_chat_started', $message->getVideoChatStarted());
             $sth->bindValue(':video_chat_ended', $message->getVideoChatEnded());

src/Entities/Chat.php

@@ -24,7 +24,10 @@
  * @method string          getUsername()                           Optional. Username, for private chats, supergroups and channels if available
  * @method string          getFirstName()                          Optional. First name of the other party in a private chat
  * @method string          getLastName()                           Optional. Last name of the other party in a private chat
+ * @method bool            getIsForum()                            Optional. True, if the supergroup chat is a forum (has topics enabled)
  * @method ChatPhoto       getPhoto()                              Optional. Chat photo. Returned only in getChat.
+ * @method string[]        getActiveUsernames()                    Optional. If non-empty, the list of all active chat usernames; for private chats, supergroups and channels. Returned only in getChat.
+ * @method string          getEmojiStatusCustomEmojiId()           Optional. Custom emoji identifier of emoji status of the other party in a private chat. Returned only in getChat.
  * @method string          getBio()                                Optional. Bio of the other party in a private chat. Returned only in getChat.
  * @method bool            getHasPrivateForwards()                 Optional. True, if privacy settings of the other party in the private chat allows to use tg://user?id=<user_id> links only in chats with the user. Returned only in getChat.
  * @method bool            getHasRestrictedVoiceAndVideoMessages() Optional. True, if the privacy settings of the other party restrict sending voice and video note messages in the private chat. Returned only in getChat.

src/Entities/ChatAdministratorRights.php

@@ -16,6 +16,7 @@
  * @method bool getCanPostMessages()     Optional. True, if the administrator can post in the channel; channels only
  * @method bool getCanEditMessages()     Optional. True, if the administrator can edit messages of other users and can pin messages; channels only
  * @method bool getCanPinMessages()      Optional. True, if the user is allowed to pin messages; groups and supergroups only
+ * @method bool getCanManageTopics()     Optional. True, if the user is allowed to create, rename, close, and reopen forum topics; supergroups only
  *
  * @method $this setIsAnonymous(bool $is_anonymous)                   True, if the user's presence in the chat is hidden
  * @method $this setCanManageChat(bool $can_manage_chat)              True, if the administrator can access the chat event log, chat statistics, message statistics in channels, see channel members, see anonymous administrators in supergroups and ignore slow mode. Implied by any other administrator privilege
@@ -28,6 +29,7 @@
  * @method $this setCanPostMessages(bool $can_post_messages)          Optional. True, if the administrator can post in the channel; channels only
  * @method $this setCanEditMessages(bool $can_edit_messages)          Optional. True, if the administrator can edit messages of other users and can pin messages; channels only
  * @method $this setCanPinMessages(bool $can_pin_messages)            Optional. True, if the user is allowed to pin messages; groups and supergroups only
+ * @method $this setCanManageTopics(bool $can_manage_topics)          Optional. True, if the user is allowed to create, rename, close, and reopen forum topics; supergroups only
  */
 class ChatAdministratorRights extends Entity
 {

src/Entities/ChatMember/ChatMemberAdministrator.php

@@ -13,18 +13,19 @@
  * @method string getStatus()              The member's status in the chat, always “administrator”
  * @method User   getUser()                Information about the user
  * @method bool   getCanBeEdited()         True, if the bot is allowed to edit administrator privileges of that user
- * @method string getCustomTitle()         Custom title for this user
  * @method bool   getIsAnonymous()         True, if the user's presence in the chat is hidden
  * @method bool   getCanManageChat()       True, if the administrator can access the chat event log, chat statistics, message statistics in channels, see channel members, see anonymous administrators in supergroups and ignore slow mode. Implied by any other administrator privilege
- * @method bool   getCanPostMessages()     True, if the administrator can post in the channel; channels only
- * @method bool   getCanEditMessages()     True, if the administrator can edit messages of other users and can pin messages; channels only
  * @method bool   getCanDeleteMessages()   True, if the administrator can delete messages of other users
  * @method bool   getCanManageVideoChats() True, if the administrator can manage video chats
  * @method bool   getCanRestrictMembers()  True, if the administrator can restrict, ban or unban chat members
  * @method bool   getCanPromoteMembers()   True, if the administrator can add new administrators with a subset of their own privileges or demote administrators that he has promoted, directly or indirectly (promoted by administrators that were appointed by the user)
  * @method bool   getCanChangeInfo()       True, if the user is allowed to change the chat title, photo and other settings
  * @method bool   getCanInviteUsers()      True, if the user is allowed to invite new users to the chat
- * @method bool   getCanPinMessages()      True, if the user is allowed to pin messages; groups and supergroups only
+ * @method bool   getCanPostMessages()     Optional. True, if the administrator can post in the channel; channels only
+ * @method bool   getCanEditMessages()     Optional. True, if the administrator can edit messages of other users and can pin messages; channels only
+ * @method bool   getCanPinMessages()      Optional. True, if the user is allowed to pin messages; groups and supergroups only
+ * @method bool   getCanManageTopics()     Optional. True, if the user is allowed to create, rename, close, and reopen forum topics; supergroups only
+ * @method string getCustomTitle()         Custom title for this user
  */
 class ChatMemberAdministrator extends Entity implements ChatMember
 {

src/Entities/ChatMember/ChatMemberRestricted.php

@@ -16,6 +16,7 @@
  * @method bool   getCanChangeInfo()         True, if the user is allowed to change the chat title, photo and other settings
  * @method bool   getCanInviteUsers()        True, if the user is allowed to invite new users to the chat
  * @method bool   getCanPinMessages()        True, if the user is allowed to pin messages; groups and supergroups only
+ * @method bool   getCanManageTopics()       True, if the user is allowed to create forum topics
  * @method bool   getCanSendMessages()       True, if the user is allowed to send text messages, contacts, locations and venues
  * @method bool   getCanSendMediaMessages()  True, if the user is allowed to send audios, documents, photos, videos, video notes and voice notes
  * @method bool   getCanSendPolls()          True, if the user is allowed to send polls

src/Entities/ChatPermissions.php

@@ -24,6 +24,7 @@
  * @method bool getCanChangeInfo()         Optional. True, if the user is allowed to change the chat title, photo and other settings. Ignored in public supergroups
  * @method bool getCanInviteUsers()        Optional. True, if the user is allowed to invite new users to the chat
  * @method bool getCanPinMessages()        Optional. True, if the user is allowed to pin messages. Ignored in public supergroups
+ * @method bool getCanManageTopics()       Optional. True, if the user is allowed to create forum topics. If omitted defaults to the value of can_pin_messages
  */
 class ChatPermissions extends Entity
 {