Bot API 7.0 - Request for multiple users

noplanman · noplanman · commit 4ba3ee961f18 · 2024-05-04T22:15:05.000+02:00
diff --git a/src/Entities/KeyboardButton.php b/src/Entities/KeyboardButton.php
@@ -11,37 +11,35 @@
 
 namespace Longman\TelegramBot\Entities;
 
-use Longman\TelegramBot\Exception\TelegramException;
-
 /**
  * Class KeyboardButton
  *
  * This object represents one button of the reply keyboard. For simple text buttons String can be used instead of this object to specify text of the button. Optional fields request_contact, request_location, and request_poll are mutually exclusive.
  *
  * @link https://core.telegram.org/bots/api#keyboardbutton
  *
- * @property KeyboardButtonRequestUser $request_user
- * @property KeyboardButtonRequestChat $request_chat
- * @property bool $request_contact
- * @property bool $request_location
- * @property KeyboardButtonPollType $request_poll
- * @property WebAppInfo $web_app
+ * @property KeyboardButtonRequestUsers $request_users
+ * @property KeyboardButtonRequestChat  $request_chat
+ * @property bool                       $request_contact
+ * @property bool                       $request_location
+ * @property KeyboardButtonPollType     $request_poll
+ * @property WebAppInfo                 $web_app
  *
- * @method string                    getText()            Text of the button. If none of the optional fields are used, it will be sent to the bot as a message when the button is pressed
- * @method KeyboardButtonRequestUser getRequestUser()     Optional. If specified, pressing the button will open a list of suitable users. Tapping on any user will send their identifier to the bot in a “user_shared” service message. Available in private chats only.
- * @method KeyboardButtonRequestChat getRequestChat()     Optional. If specified, pressing the button will open a list of suitable chats. Tapping on a chat will send its identifier to the bot in a “chat_shared” service message. Available in private chats only.
- * @method bool                      getRequestContact()  Optional. If True, the user's phone number will be sent as a contact when the button is pressed. Available in private chats only
- * @method bool                      getRequestLocation() Optional. If True, the user's current location will be sent when the button is pressed. Available in private chats only
- * @method KeyboardButtonPollType    getRequestPoll()     Optional. If specified, the user will be asked to create a poll and send it to the bot when the button is pressed. Available in private chats only
- * @method WebAppInfo                getWebApp()          Optional. If specified, the described Web App will be launched when the button is pressed. The Web App will be able to send a “web_app_data” service message. Available in private chats only.
+ * @method string                     getText()            Text of the button. If none of the optional fields are used, it will be sent to the bot as a message when the button is pressed
+ * @method KeyboardButtonRequestUsers getRequestUsers()    Optional. If specified, pressing the button will open a list of suitable users. Identifiers of selected users will be sent to the bot in a “users_shared” service message. Available in private chats only.
+ * @method KeyboardButtonRequestChat  getRequestChat()     Optional. If specified, pressing the button will open a list of suitable chats. Tapping on a chat will send its identifier to the bot in a “chat_shared” service message. Available in private chats only.
+ * @method bool                       getRequestContact()  Optional. If True, the user's phone number will be sent as a contact when the button is pressed. Available in private chats only
+ * @method bool                       getRequestLocation() Optional. If True, the user's current location will be sent when the button is pressed. Available in private chats only
+ * @method KeyboardButtonPollType     getRequestPoll()     Optional. If specified, the user will be asked to create a poll and send it to the bot when the button is pressed. Available in private chats only
+ * @method WebAppInfo                 getWebApp()          Optional. If specified, the described Web App will be launched when the button is pressed. The Web App will be able to send a “web_app_data” service message. Available in private chats only.
  *
- * @method $this setText(string $text)                                   Text of the button. If none of the optional fields are used, it will be sent to the bot as a message when the button is pressed
- * @method $this setRequestUser(KeyboardButtonRequestUser $request_user) Optional. If specified, pressing the button will open a list of suitable users. Tapping on any user will send their identifier to the bot in a “user_shared” service message. Available in private chats only.
- * @method $this setRequestChat(KeyboardButtonRequestChat $request_chat) Optional. If specified, pressing the button will open a list of suitable chats. Tapping on a chat will send its identifier to the bot in a “chat_shared” service message. Available in private chats only.
- * @method $this setRequestContact(bool $request_contact)                Optional. If True, the user's phone number will be sent as a contact when the button is pressed. Available in private chats only
- * @method $this setRequestLocation(bool $request_location)              Optional. If True, the user's current location will be sent when the button is pressed. Available in private chats only
- * @method $this setRequestPoll(KeyboardButtonPollType $request_poll)    Optional. If specified, the user will be asked to create a poll and send it to the bot when the button is pressed. Available in private chats only
- * @method $this setWebApp(WebAppInfo $web_app)                          Optional. If specified, the described Web App will be launched when the button is pressed. The Web App will be able to send a “web_app_data” service message. Available in private chats only.
+ * @method $this setText(string $text)                                      Text of the button. If none of the optional fields are used, it will be sent to the bot as a message when the button is pressed
+ * @method $this setRequestUsers(KeyboardButtonRequestUsers $request_users) Optional. If specified, pressing the button will open a list of suitable users. Identifiers of selected users will be sent to the bot in a “users_shared” service message. Available in private chats only.
+ * @method $this setRequestChat(KeyboardButtonRequestChat $request_chat)    Optional. If specified, pressing the button will open a list of suitable chats. Tapping on a chat will send its identifier to the bot in a “chat_shared” service message. Available in private chats only.
+ * @method $this setRequestContact(bool $request_contact)                   Optional. If True, the user's phone number will be sent as a contact when the button is pressed. Available in private chats only
+ * @method $this setRequestLocation(bool $request_location)                 Optional. If True, the user's current location will be sent when the button is pressed. Available in private chats only
+ * @method $this setRequestPoll(KeyboardButtonPollType $request_poll)       Optional. If specified, the user will be asked to create a poll and send it to the bot when the button is pressed. Available in private chats only
+ * @method $this setWebApp(WebAppInfo $web_app)                             Optional. If specified, the described Web App will be launched when the button is pressed. The Web App will be able to send a “web_app_data” service message. Available in private chats only.
  */
 class KeyboardButton extends Entity
 {
@@ -59,10 +57,10 @@ public function __construct($data)
     protected function subEntities(): array
     {
         return [
-            'request_user' => KeyboardButtonRequestUser::class,
-            'request_chat' => KeyboardButtonRequestChat::class,
-            'request_poll' => KeyboardButtonPollType::class,
-            'web_app'      => WebAppInfo::class,
+            'request_users' => KeyboardButtonRequestUsers::class,
+            'request_chat'  => KeyboardButtonRequestChat::class,
+            'request_poll'  => KeyboardButtonPollType::class,
+            'web_app'       => WebAppInfo::class,
         ];
     }
 
@@ -84,8 +82,8 @@ public static function couldBe(array $data): bool
     public function __call($method, $args)
     {
         // Only 1 of these can be set, so clear the others when setting a new one.
-        if (in_array($method, ['setRequestUser', 'setRequestChat', 'setRequestContact', 'setRequestLocation', 'setRequestPoll', 'setWebApp'], true)) {
-            unset($this->reqest_user, $this->request_chat, $this->request_contact, $this->request_location, $this->request_poll, $this->web_app);
+        if (in_array($method, ['setRequestUsers', 'setRequestChat', 'setRequestContact', 'setRequestLocation', 'setRequestPoll', 'setWebApp'], true)) {
+            unset($this->request_users, $this->request_chat, $this->request_contact, $this->request_location, $this->request_poll, $this->web_app);
         }
 
         return parent::__call($method, $args);
diff --git a/src/Entities/KeyboardButtonRequestUsers.php b/src/Entities/KeyboardButtonRequestUsers.php
@@ -3,21 +3,21 @@
 namespace Longman\TelegramBot\Entities;
 
 /**
- * Class KeyboardButtonRequestUser
+ * This object defines the criteria used to request suitable users. The identifiers of the selected users will be shared with the bot when the corresponding button is pressed.
  *
- * This entity defines the criteria used to request a suitable user. The identifier of the selected user will be shared with the bot when the corresponding button is pressed.
- *
- * @link https://core.telegram.org/bots/api#keyboardbuttonrequestuser
+ * @link https://core.telegram.org/bots/api#keyboardbuttonrequestusers
  *
  * @method int  getRequestId()     Signed 32-bit identifier of the request, which will be received back in the UserShared object. Must be unique within the message
  * @method bool getUserIsBot()     Optional. Pass True to request a bot, pass False to request a regular user. If not specified, no additional restrictions are applied.
  * @method bool getUserIsPremium() Optional. Pass True to request a premium user, pass False to request a non-premium user. If not specified, no additional restrictions are applied.
+ * @method int  getMaxQuantity()   Optional. The maximum number of users to be selected; 1-10. Defaults to 1.
  *
  * @method $this setRequestId(int $request_id)           Signed 32-bit identifier of the request, which will be received back in the UserShared object. Must be unique within the message
  * @method $this setUserIsBot(bool $user_is_bot)         Optional. Pass True to request a bot, pass False to request a regular user. If not specified, no additional restrictions are applied.
  * @method $this setUserIsPremium(bool $user_is_premium) Optional. Pass True to request a premium user, pass False to request a non-premium user. If not specified, no additional restrictions are applied.
+ * @method int   setMaxQuantity(int $set_max_quantity)   Optional. The maximum number of users to be selected; 1-10. Defaults to 1.
  */
-class KeyboardButtonRequestUser extends Entity
+class KeyboardButtonRequestUsers extends Entity
 {
 
 }
diff --git a/src/Entities/Message.php b/src/Entities/Message.php
@@ -85,7 +85,7 @@
  * @method Message                                getPinnedMessage()                          Optional. Specified message was pinned. Note that the Message object in this field will not contain further reply_to_message fields even if it is itself a reply.
  * @method Invoice                                getInvoice()                                Optional. Message is an invoice for a payment, information about the invoice.
  * @method SuccessfulPayment                      getSuccessfulPayment()                      Optional. Message is a service message about a successful payment, information about the payment.
- * @method UserShared                             getUserShared()                             Optional. Service message: a user was shared with the bot
+ * @method UsersShared                            getUsersShared()                            Optional. Service message: users were shared with the bot
  * @method ChatShared                             getChatShared()                             Optional. Service message: a chat was shared with the bot
  * @method string                                 getConnectedWebsite()                       Optional. The domain name of the website on which the user has logged in.
  * @method WriteAccessAllowed                     getWriteAccessAllowed()                     Optional. Service message: the user allowed the bot added to the attachment menu to write messages
@@ -146,7 +146,7 @@ protected function subEntities(): array
             'pinned_message'                    => __CLASS__,
             'invoice'                           => Invoice::class,
             'successful_payment'                => SuccessfulPayment::class,
-            'user_shared'                       => UserShared::class,
+            'users_shared'                      => UsersShared::class,
             'chat_shared'                       => ChatShared::class,
             'write_access_allowed'              => WriteAccessAllowed::class,
             'passport_data'                     => PassportData::class,
@@ -292,7 +292,7 @@ public function getType(): string
             'pinned_message',
             'invoice',
             'successful_payment',
-            'user_shared',
+            'users_shared',
             'chat_shared',
             'write_access_allowed',
             'passport_data',
diff --git a/src/Entities/UserShared.php b/src/Entities/UserShared.php
diff --git a/src/Entities/UsersShared.php b/src/Entities/UsersShared.php
@@ -0,0 +1,16 @@
+<?php
+
+namespace Longman\TelegramBot\Entities;
+
+/**
+ * This object contains information about the users whose identifiers were shared with the bot using a KeyboardButtonRequestUsers button.
+ *
+ * @link https://core.telegram.org/bots/api#usersshared
+ *
+ * @method int   getRequestId() Identifier of the request
+ * @method int[] getUserIds()   Identifier of the shared users.
+ */
+class UsersShared extends Entity
+{
+
+}
diff --git a/structure.sql b/structure.sql
@@ -162,7 +162,7 @@ CREATE TABLE IF NOT EXISTS `message` (
   `pinned_message` TEXT NULL COMMENT 'Message object. Specified message was pinned',
   `invoice` TEXT NULL COMMENT 'Message is an invoice for a payment, information about the invoice',
   `successful_payment` TEXT NULL COMMENT 'Message is a service message about a successful payment, information about the payment',
-  `user_shared` TEXT NULL COMMENT 'Optional. Service message: a user was shared with the bot',
+  `users_shared` TEXT NULL COMMENT 'Optional. Service message: users were shared with the bot',
   `chat_shared` TEXT NULL COMMENT 'Optional. Service message: a chat was shared with the bot',
   `connected_website` TEXT NULL COMMENT 'The domain name of the website on which the user has logged in.',
   `write_access_allowed` TEXT DEFAULT NULL COMMENT 'Service message: the user allowed the bot added to the attachment menu to write messages',
diff --git a/utils/db-schema-update/0.82.0-unreleased.sql b/utils/db-schema-update/0.82.0-unreleased.sql
@@ -33,7 +33,8 @@ CREATE TABLE IF NOT EXISTS `message_reaction_count` (
 
 ALTER TABLE `message`
     ADD COLUMN `external_reply`       TEXT NULL DEFAULT NULL COMMENT 'Optional. Information about the message that is being replied to, which may come from another chat or forum topic' AFTER `reply_to_message`,
-    ADD COLUMN `link_preview_options` TEXT NULL DEFAULT NULL COMMENT 'Optional. Options used for link preview generation for the message, if it is a text message and link preview options were changed' AFTER `via_bot`;
+    ADD COLUMN `link_preview_options` TEXT NULL DEFAULT NULL COMMENT 'Optional. Options used for link preview generation for the message, if it is a text message and link preview options were changed' AFTER `via_bot`,
+    RENAME COLUMN `user_shared` TO `users_shared`;
 
 ALTER TABLE `telegram_update`
     ADD COLUMN `message_reaction_id`       bigint UNSIGNED DEFAULT NULL COMMENT 'A reaction to a message was changed by a user' AFTER `edited_channel_post_id`,

Original file line number	Diff line number	Diff line change
`@@ -3,21 +3,21 @@`
`3`	`3`	`namespace Longman\TelegramBot\Entities;`
`4`	`4`
`5`	`5`	`/**`
`6`		`- * Class KeyboardButtonRequestUser`
	`6`	`+ * This object defines the criteria used to request suitable users. The identifiers of the selected users will be shared with the bot when the corresponding button is pressed.`
`7`	`7`	`*`
`8`		`- * This entity defines the criteria used to request a suitable user. The identifier of the selected user will be shared with the bot when the corresponding button is pressed.`
`9`		`- *`
`10`		`- * @link https://core.telegram.org/bots/api#keyboardbuttonrequestuser`
	`8`	`+ * @link https://core.telegram.org/bots/api#keyboardbuttonrequestusers`
`11`	`9`	`*`
`12`	`10`	`* @method int getRequestId() Signed 32-bit identifier of the request, which will be received back in the UserShared object. Must be unique within the message`
`13`	`11`	`* @method bool getUserIsBot() Optional. Pass True to request a bot, pass False to request a regular user. If not specified, no additional restrictions are applied.`
`14`	`12`	`* @method bool getUserIsPremium() Optional. Pass True to request a premium user, pass False to request a non-premium user. If not specified, no additional restrictions are applied.`
	`13`	`+ * @method int getMaxQuantity() Optional. The maximum number of users to be selected; 1-10. Defaults to 1.`
`15`	`14`	`*`
`16`	`15`	`* @method $this setRequestId(int $request_id) Signed 32-bit identifier of the request, which will be received back in the UserShared object. Must be unique within the message`
`17`	`16`	`* @method $this setUserIsBot(bool $user_is_bot) Optional. Pass True to request a bot, pass False to request a regular user. If not specified, no additional restrictions are applied.`
`18`	`17`	`* @method $this setUserIsPremium(bool $user_is_premium) Optional. Pass True to request a premium user, pass False to request a non-premium user. If not specified, no additional restrictions are applied.`
	`18`	`+ * @method int setMaxQuantity(int $set_max_quantity) Optional. The maximum number of users to be selected; 1-10. Defaults to 1.`
`19`	`19`	`*/`
`20`		`-class KeyboardButtonRequestUser extends Entity`
	`20`	`+class KeyboardButtonRequestUsers extends Entity`
`21`	`21`	`{`
`22`	`22`
`23`	`23`	`}`