Merge pull request #1266 from php-telegram-bot/api-5.4

Bot API 5.4

Author: noplanman

CHANGELOG.md

@@ -7,6 +7,7 @@ Exclamation symbols (:exclamation:) note something of importance e.g. breaking c
 ### Notes
 - [:ledger: View file changes][Unreleased] ∙ [:page_with_curl: DB migration script][unreleased-sql-migration]
 ### Added
+- Bot API 5.4. (@TiiFuchs, @noplanman) (#1266)
 ### Changed
 ### Deprecated
 ### Removed

src/ChatAction.php

@@ -33,25 +33,11 @@ class ChatAction
      */
     public const UPLOAD_VIDEO = 'upload_video';
 
-    /**
-     * Record Audio chat action
-     *
-     * @deprecated Use ChatAction::RECORD_VOICE instead
-     */
-    public const RECORD_AUDIO = 'record_voice';
-
     /**
      * Record Voice chat action
      */
     public const RECORD_VOICE = 'record_voice';
 
-    /**
-     * Upload Audio chat action
-     *
-     * @deprecated Use ChatAction::UPLOAD_VOICE instead
-     */
-    public const UPLOAD_AUDIO = 'upload_voice';
-
     /**
      * Upload Voice chat action
      */
@@ -62,6 +48,11 @@ class ChatAction
      */
     public const UPLOAD_DOCUMENT = 'upload_document';
 
+    /**
+     * Choose Sticker chat action
+     */
+    public const CHOOSE_STICKER = 'choose_sticker';
+
     /**
      * Find Location chat action
      */

src/DB.php

@@ -348,7 +348,8 @@ protected static function insertTelegramUpdate(
         ?string $poll_id = null,
         ?string $poll_answer_poll_id = null,
         ?string $my_chat_member_updated_id = null,
-        ?string $chat_member_updated_id = null
+        ?string $chat_member_updated_id = null,
+        ?string $chat_join_request_id = null
     ): ?bool {
         if ($message_id === null && $edited_message_id === null && $channel_post_id === null && $edited_channel_post_id === null && $inline_query_id === null && $chosen_inline_result_id === null && $callback_query_id === null && $shipping_query_id === null && $pre_checkout_query_id === null && $poll_id === null && $poll_answer_poll_id === null && $my_chat_member_updated_id === null && $chat_member_updated_id === null) {
             throw new TelegramException('message_id, edited_message_id, channel_post_id, edited_channel_post_id, inline_query_id, chosen_inline_result_id, callback_query_id, shipping_query_id, pre_checkout_query_id, poll_id, poll_answer_poll_id, my_chat_member_updated_id, chat_member_updated_id are all null');
@@ -361,9 +362,19 @@ protected static function insertTelegramUpdate(
         try {
             $sth = self::$pdo->prepare('
                 INSERT IGNORE INTO `' . TB_TELEGRAM_UPDATE . '`
-                (`id`, `chat_id`, `message_id`, `edited_message_id`, `channel_post_id`, `edited_channel_post_id`, `inline_query_id`, `chosen_inline_result_id`, `callback_query_id`, `shipping_query_id`, `pre_checkout_query_id`, `poll_id`, `poll_answer_poll_id`, `my_chat_member_updated_id`, `chat_member_updated_id`)
-                VALUES
-                (:id, :chat_id, :message_id, :edited_message_id, :channel_post_id, :edited_channel_post_id, :inline_query_id, :chosen_inline_result_id, :callback_query_id, :shipping_query_id, :pre_checkout_query_id, :poll_id, :poll_answer_poll_id, :my_chat_member_updated_id, :chat_member_updated_id)
+                (
+                    `id`, `chat_id`, `message_id`, `edited_message_id`,
+                    `channel_post_id`, `edited_channel_post_id`, `inline_query_id`, `chosen_inline_result_id`,
+                    `callback_query_id`, `shipping_query_id`, `pre_checkout_query_id`,
+                    `poll_id`, `poll_answer_poll_id`, `my_chat_member_updated_id`, `chat_member_updated_id`,
+                    `chat_join_request_id`
+                ) VALUES (
+                    :id, :chat_id, :message_id, :edited_message_id,
+                    :channel_post_id, :edited_channel_post_id, :inline_query_id, :chosen_inline_result_id,
+                    :callback_query_id, :shipping_query_id, :pre_checkout_query_id,
+                    :poll_id, :poll_answer_poll_id, :my_chat_member_updated_id, :chat_member_updated_id,
+                    :chat_join_request_id
+                )
             ');
 
             $sth->bindValue(':id', $update_id);
@@ -381,6 +392,7 @@ protected static function insertTelegramUpdate(
             $sth->bindValue(':poll_answer_poll_id', $poll_answer_poll_id);
             $sth->bindValue(':my_chat_member_updated_id', $my_chat_member_updated_id);
             $sth->bindValue(':chat_member_updated_id', $chat_member_updated_id);
+            $sth->bindValue(':chat_join_request_id', $chat_join_request_id);
 
             return $sth->execute();
         } catch (PDOException $e) {
@@ -547,6 +559,7 @@ public static function insertRequest(Update $update): bool
         $poll_answer_poll_id       = null;
         $my_chat_member_updated_id = null;
         $chat_member_updated_id    = null;
+        $chat_join_request_id      = null;
 
         if (($message = $update->getMessage()) && self::insertMessageRequest($message)) {
             $chat_id    = $message->getChat()->getId();
@@ -578,6 +591,8 @@ public static function insertRequest(Update $update): bool
             $my_chat_member_updated_id = self::$pdo->lastInsertId();
         } elseif (($chat_member = $update->getChatMember()) && self::insertChatMemberUpdatedRequest($chat_member)) {
             $chat_member_updated_id = self::$pdo->lastInsertId();
+        } elseif (($chat_join_request = $update->getChatJoinRequest()) && self::insertChatJoinRequestRequest($chat_join_request)) {
+            $chat_join_request_id = self::$pdo->lastInsertId();
         } else {
             return false;
         }
@@ -597,7 +612,8 @@ public static function insertRequest(Update $update): bool
             $poll_id,
             $poll_answer_poll_id,
             $my_chat_member_updated_id,
-            $chat_member_updated_id
+            $chat_member_updated_id,
+            $chat_join_request_id
         );
     }
 
@@ -989,6 +1005,54 @@ public static function insertChatMemberUpdatedRequest(ChatMemberUpdated $chat_me
         }
     }
 
+    /**
+     * Insert chat join request into database
+     *
+     * @param ChatJoinRequest $chat_join_request
+     *
+     * @return bool If the insert was successful
+     * @throws TelegramException
+     */
+    public static function insertChatJoinRequestRequest(ChatJoinRequest $chat_join_request): bool
+    {
+        if (!self::isDbConnected()) {
+            return false;
+        }
+
+        try {
+            $sth = self::$pdo->prepare('
+                INSERT INTO `' . TB_CHAT_MEMBER_UPDATED . '`
+                (`chat_id`, `user_id`, `date`, `bio`, `invite_link`, `created_at`)
+                VALUES
+                (:chat_id, :user_id, :date, :bio, :invite_link, :created_at)
+            ');
+
+            $date    = self::getTimestamp();
+            $chat_id = null;
+            $user_id = null;
+
+            if ($chat = $chat_join_request->getChat()) {
+                $chat_id = $chat->getId();
+                self::insertChat($chat, $date);
+            }
+            if ($user = $chat_join_request->getFrom()) {
+                $user_id = $user->getId();
+                self::insertUser($user, $date);
+            }
+
+            $sth->bindValue(':chat_id', $chat_id);
+            $sth->bindValue(':user_id', $user_id);
+            $sth->bindValue(':date', self::getTimestamp($chat_join_request->getDate()));
+            $sth->bindValue(':bio', $chat_join_request->getBio());
+            $sth->bindValue(':invite_link', $chat_join_request->getInviteLink());
+            $sth->bindValue(':created_at', $date);
+
+            return $sth->execute();
+        } catch (PDOException $e) {
+            throw new TelegramException($e->getMessage());
+        }
+    }
+
     /**
      * Insert Message request in db
      *

src/Entities/ChatInviteLink.php

@@ -18,12 +18,15 @@
  *
  * @link https://core.telegram.org/bots/api#chatinvitelink
  *
- * @method string  GetInviteLink()       The invite link. If the link was created by another chat administrator, then the second part of the link will be replaced with “…”
- * @method User    getCreator()          Creator of the link
- * @method bool    getIsPrimary()        True, if the link is primary
- * @method bool    getIsRevoked()        True, if the link is revoked
- * @method int     getExpireDate()       Optional. Point in time (Unix timestamp) when the link will expire or has been expired
- * @method int     getMemberLimit()      Optional. Maximum number of users that can be members of the chat simultaneously after joining the chat via this invite link; 1-99999
+ * @method string  GetInviteLink()              The invite link. If the link was created by another chat administrator, then the second part of the link will be replaced with “…”
+ * @method User    getCreator()                 Creator of the link
+ * @method bool    getCreatesJoinRequest()      True, if users joining the chat via the link need to be approved by chat administrators
+ * @method bool    getIsPrimary()               True, if the link is primary
+ * @method bool    getIsRevoked()               True, if the link is revoked
+ * @method string  getName()                    Optional. Invite link name
+ * @method int     getExpireDate()              Optional. Point in time (Unix timestamp) when the link will expire or has been expired
+ * @method int     getMemberLimit()             Optional. Maximum number of users that can be members of the chat simultaneously after joining the chat via this invite link; 1-99999
+ * @method int     getPendingJoinRequestCount() Optional. Number of pending join requests created using this link
  */
 class ChatInviteLink extends Entity
 {

src/Entities/ChatJoinRequest.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace Longman\TelegramBot\Entities;
+
+/**
+ * Class ChatJoinRequest
+ *
+ * Represents a join request sent to a chat.
+ *
+ * @link https://core.telegram.org/bots/api#chatjoinrequest
+ *
+ * @method Chat           getChat()       Chat to which the request was sent
+ * @method User           getFrom()       User that sent the join request
+ * @method int            getDate()       Date the request was sent in Unix time
+ * @method string         getBio()        Optional. Bio of the user.
+ * @method ChatInviteLink getInviteLink() Optional. Chat invite link that was used by the user to send the join request
+ */
+class ChatJoinRequest extends Entity
+{
+
+    protected function subEntities(): array
+    {
+        return [
+            'chat'        => Chat::class,
+            'from'        => User::class,
+            'invite_link' => ChatInviteLink::class,
+        ];
+    }
+
+}

src/Entities/Update.php

@@ -33,6 +33,7 @@
  * @method PollAnswer          getPollAnswer()         Optional. A user changed their answer in a non-anonymous poll. Bots receive new votes only in polls that were sent by the bot itself.
  * @method ChatMemberUpdated   getMyChatMember()       Optional. The bot's chat member status was updated in a chat. For private chats, this update is received only when the bot is blocked or unblocked by the user.
  * @method ChatMemberUpdated   getChatMember()         Optional. A chat member's status was updated in a chat. The bot must be an administrator in the chat and must explicitly specify “chat_member” in the list of allowed_updates to receive these updates.
+ * @method ChatJoinRequest     getChatJoinRequest()    Optional. A request to join the chat has been sent. The bot must have the can_invite_users administrator right in the chat to receive these updates.
  */
 class Update extends Entity
 {
@@ -49,6 +50,7 @@ class Update extends Entity
     public const TYPE_POLL_ANSWER          = 'poll_answer';
     public const TYPE_MY_CHAT_MEMBER       = 'my_chat_member';
     public const TYPE_CHAT_MEMBER          = 'chat_member';
+    public const TYPE_CHAT_JOIN_REQUEST    = 'chat_join_request';
 
     /**
      * {@inheritdoc}
@@ -69,6 +71,7 @@ protected function subEntities(): array
             self::TYPE_POLL_ANSWER          => PollAnswer::class,
             self::TYPE_MY_CHAT_MEMBER       => ChatMemberUpdated::class,
             self::TYPE_CHAT_MEMBER          => ChatMemberUpdated::class,
+            self::TYPE_CHAT_JOIN_REQUEST    => ChatJoinRequest::class,
         ];
     }
 

src/Request.php

@@ -64,6 +64,8 @@
  * @method static ServerResponse createChatInviteLink(array $data)            Use this method to create an additional invite link for a chat. The bot must be an administrator in the chat for this to work and must have the appropriate admin rights. The link can be revoked using the method revokeChatInviteLink. Returns the new invite link as ChatInviteLink object.
  * @method static ServerResponse editChatInviteLink(array $data)              Use this method to edit a non-primary invite link created by the bot. The bot must be an administrator in the chat for this to work and must have the appropriate admin rights. Returns the edited invite link as a ChatInviteLink object.
  * @method static ServerResponse revokeChatInviteLink(array $data)            Use this method to revoke an invite link created by the bot. If the primary link is revoked, a new link is automatically generated. The bot must be an administrator in the chat for this to work and must have the appropriate admin rights. Returns the revoked invite link as ChatInviteLink object.
+ * @method static ServerResponse approveChatJoinRequest(array $data)          Use this method to approve a chat join request. The bot must be an administrator in the chat for this to work and must have the can_invite_users administrator right. Returns True on success.
+ * @method static ServerResponse declineChatJoinRequest(array $data)          Use this method to decline a chat join request. The bot must be an administrator in the chat for this to work and must have the can_invite_users administrator right. Returns True on success.
  * @method static ServerResponse setChatPhoto(array $data)                    Use this method to set a new profile photo for the chat. Photos can't be changed for private chats. The bot must be an administrator in the chat for this to work and must have the appropriate admin rights. Returns True on success.
  * @method static ServerResponse deleteChatPhoto(array $data)                 Use this method to delete a chat photo. Photos can't be changed for private chats. The bot must be an administrator in the chat for this to work and must have the appropriate admin rights. Returns True on success.
  * @method static ServerResponse setChatTitle(array $data)                    Use this method to change the title of a chat. Titles can't be changed for private chats. The bot must be an administrator in the chat for this to work and must have the appropriate admin rights. Returns True on success.
@@ -204,6 +206,8 @@ class Request
         'createChatInviteLink',
         'editChatInviteLink',
         'revokeChatInviteLink',
+        'approveChatJoinRequest',
+        'declineChatJoinRequest',
         'setChatPhoto',
         'deleteChatPhoto',
         'setChatTitle',

structure.sql

@@ -260,6 +260,21 @@ CREATE TABLE IF NOT EXISTS `chat_member_updated` (
   FOREIGN KEY (`user_id`) REFERENCES `user` (`id`)
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_520_ci;
 
+CREATE TABLE IF NOT EXISTS `chat_join_request` (
+  `id` BIGINT UNSIGNED AUTO_INCREMENT COMMENT 'Unique identifier for this entry',
+  `chat_id` BIGINT NOT NULL COMMENT 'Chat to which the request was sent',
+  `user_id` BIGINT NOT NULL COMMENT 'User that sent the join request',
+  `date` TIMESTAMP NOT NULL COMMENT 'Date the request was sent in Unix time',
+  `bio` TEXT NOT NULL COMMENT 'Optional. Bio of the user',
+  `invite_link` TEXT NULL COMMENT 'Optional. Chat invite link that was used by the user to send the join request',
+  `created_at` timestamp NULL DEFAULT NULL COMMENT 'Entry date creation',
+
+  PRIMARY KEY (`id`),
+
+  FOREIGN KEY (`chat_id`) REFERENCES `chat` (`id`),
+  FOREIGN KEY (`user_id`) REFERENCES `user` (`id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_520_ci;
+
 CREATE TABLE IF NOT EXISTS `telegram_update` (
   `id` bigint UNSIGNED COMMENT 'Update''s unique identifier',
   `chat_id` bigint NULL DEFAULT NULL COMMENT 'Unique chat identifier',
@@ -276,6 +291,7 @@ CREATE TABLE IF NOT EXISTS `telegram_update` (
   `poll_answer_poll_id` bigint UNSIGNED DEFAULT NULL COMMENT 'A user changed their answer in a non-anonymous poll. Bots receive new votes only in polls that were sent by the bot itself.',
   `my_chat_member_updated_id` BIGINT UNSIGNED NULL COMMENT 'The bot''s chat member status was updated in a chat. For private chats, this update is received only when the bot is blocked or unblocked by the user.',
   `chat_member_updated_id` BIGINT UNSIGNED NULL COMMENT 'A chat member''s status was updated in a chat. The bot must be an administrator in the chat and must explicitly specify “chat_member” in the list of allowed_updates to receive these updates.',
+  `chat_join_request_id` BIGINT UNSIGNED NULL COMMENT 'A request to join the chat has been sent',
 
   PRIMARY KEY (`id`),
   KEY `message_id` (`message_id`),
@@ -292,6 +308,7 @@ CREATE TABLE IF NOT EXISTS `telegram_update` (
   KEY `poll_answer_poll_id` (`poll_answer_poll_id`),
   KEY `my_chat_member_updated_id` (`my_chat_member_updated_id`),
   KEY `chat_member_updated_id` (`chat_member_updated_id`),
+  KEY `chat_join_request_id` (`chat_join_request_id`),
 
   FOREIGN KEY (`chat_id`, `message_id`) REFERENCES `message` (`chat_id`, `id`),
   FOREIGN KEY (`edited_message_id`) REFERENCES `edited_message` (`id`),
@@ -305,7 +322,8 @@ CREATE TABLE IF NOT EXISTS `telegram_update` (
   FOREIGN KEY (`poll_id`) REFERENCES `poll` (`id`),
   FOREIGN KEY (`poll_answer_poll_id`) REFERENCES `poll_answer` (`poll_id`),
   FOREIGN KEY (`my_chat_member_updated_id`) REFERENCES `chat_member_updated` (`id`),
-  FOREIGN KEY (`chat_member_updated_id`) REFERENCES `chat_member_updated` (`id`)
+  FOREIGN KEY (`chat_member_updated_id`) REFERENCES `chat_member_updated` (`id`),
+  FOREIGN KEY (`chat_join_request_id`) REFERENCES `chat_join_request` (`id`)
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_520_ci;
 
 CREATE TABLE IF NOT EXISTS `conversation` (

utils/db-schema-update/0.74.0-unreleased.sql

@@ -0,0 +1,17 @@
+CREATE TABLE IF NOT EXISTS `chat_join_request` (
+    `id` BIGINT UNSIGNED AUTO_INCREMENT COMMENT 'Unique identifier for this entry',
+    `chat_id` BIGINT NOT NULL COMMENT 'Chat to which the request was sent',
+    `user_id` BIGINT NOT NULL COMMENT 'User that sent the join request',
+    `date` TIMESTAMP NOT NULL COMMENT 'Date the request was sent in Unix time',
+    `bio` TEXT NOT NULL COMMENT 'Optional. Bio of the user',
+    `invite_link` TEXT NULL COMMENT 'Optional. Chat invite link that was used by the user to send the join request',
+    `created_at` timestamp NULL DEFAULT NULL COMMENT 'Entry date creation',
+
+    PRIMARY KEY (`id`),
+
+    FOREIGN KEY (`chat_id`) REFERENCES `chat` (`id`),
+    FOREIGN KEY (`user_id`) REFERENCES `user` (`id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_520_ci;
+
+ALTER TABLE `telegram_update` ADD COLUMN `chat_join_request_id` BIGINT UNSIGNED NULL COMMENT 'A request to join the chat has been sent';
+ALTER TABLE `telegram_update` ADD FOREIGN KEY (`chat_join_request_id`) REFERENCES `chat_join_request` (`id`);