Merge pull request #675 from noplanman/bot_api_3.4

Bot api 3.4

CHANGELOG.md

@@ -6,6 +6,7 @@ Exclamation symbols (:exclamation:) note something of importance e.g. breaking c
 ## [Unreleased]
 ### Added
 - Finish implementing payments, adding all missing type checks and docblock methods.
+- Implemented new changes for Bot API 3.4 (Live Locations).
 ### Changed
 - [:exclamation:][unreleased-bc-messagegetcommand-return-value] `Message::getCommand()` returns `null` if not a command, instead of `false`.
 ### Deprecated

src/Entities/Chat.php

@@ -25,6 +25,8 @@ namespace Longman\TelegramBot\Entities;
  * @property ChatPhoto $photo                           Optional. Chat photo. Returned only in getChat.
  * @property string    $description                     Optional. Description, for supergroups and channel chats. Returned only in getChat.
  * @property string    $invite_link                     Optional. Chat invite link, for supergroups and channel chats. Returned only in getChat.
+ * @property string    $sticker_set_name                Optional. For supergroups, name of Group sticker set. Returned only in getChat.
+ * @property bool      $can_set_sticker_set             Optional. True, if the bot can change group the sticker set. Returned only in getChat.
  * @method   int       getId()                          Unique identifier for this chat. This number may be greater than 32 bits and some programming languages may have difficulty/silent defects in interpreting it. But it smaller than 52 bits, so a signed 64 bit integer or double-precision float type are safe for storing this identifier.
  * @method   string    getType()                        Type of chat, can be either "private ", "group", "supergroup" or "channel"
  * @method   string    getTitle()                       Optional. Title, for channels and group chats
@@ -36,6 +38,8 @@ namespace Longman\TelegramBot\Entities;
  * @method   string    getDescription()                 Optional. Description, for supergroups and channel chats. Returned only in getChat.
  * @method   string    getInviteLink()                  Optional. Chat invite link, for supergroups and channel chats. Returned only in getChat.
  * @method   Message   getPinnedMessage()               Optional. Pinned message, for supergroups. Returned only in getChat.
+ * @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 group the sticker set. Returned only in getChat.
  */
 class Chat extends Entity
 {

src/Entities/InlineQuery/InlineQueryResultLocation.php

@@ -24,6 +24,7 @@ use Longman\TelegramBot\Entities\InputMessageContent\InputMessageContent;
  *   'latitude'              => 36.0338,
  *   'longitude'             => 71.8601,
  *   'title'                 => '',
+ *   'live_period'           => 900,
  *   'reply_markup'          => <InlineKeyboard>,
  *   'input_message_content' => <InputMessageContent>,
  *   'thumb_url'             => '',
@@ -37,6 +38,7 @@ use Longman\TelegramBot\Entities\InputMessageContent\InputMessageContent;
  * @method float                getLatitude()            Location latitude in degrees
  * @method float                getLongitude()           Location longitude in degrees
  * @method string               getTitle()               Location title
+ * @method int                  getLivePeriod()          Optional. Period in seconds for which the location can be updated, should be between 60 and 86400.
  * @method InlineKeyboard       getReplyMarkup()         Optional. Inline keyboard attached to the message
  * @method InputMessageContent  getInputMessageContent() Optional. Content of the message to be sent instead of the location
  * @method string               getThumbUrl()            Optional. Url of the thumbnail for the result
@@ -47,6 +49,7 @@ use Longman\TelegramBot\Entities\InputMessageContent\InputMessageContent;
  * @method $this setLatitude(float $latitude)                                       Location latitude in degrees
  * @method $this setLongitude(float $longitude)                                     Location longitude in degrees
  * @method $this setTitle(string $title)                                            Location title
+ * @method $this setLivePeriod(int $live_period)                                    Optional. Period in seconds for which the location can be updated, should be between 60 and 86400.
  * @method $this setReplyMarkup(InlineKeyboard $reply_markup)                       Optional. Inline keyboard attached to the message
  * @method $this setInputMessageContent(InputMessageContent $input_message_content) Optional. Content of the message to be sent instead of the location
  * @method $this setThumbUrl(string $thumb_url)                                     Optional. Url of the thumbnail for the result

src/Entities/InputMessageContent/InputLocationMessageContent.php

@@ -19,15 +19,18 @@ use Longman\TelegramBot\Entities\InlineQuery\InlineEntity;
  *
  * <code>
  * $data = [
- *   'latitude'  => 36.0338,
- *   'longitude' => 71.8601,
+ *   'latitude'    => 36.0338,
+ *   'longitude'   => 71.8601,
+ *   'live_period' => 900,
  * ];
  *
- * @method float getLatitude()  Latitude of the location in degrees
- * @method float getLongitude() Longitude of the location in degrees
+ * @method float getLatitude()   Latitude of the location in degrees
+ * @method float getLongitude()  Longitude of the location in degrees
+ * @method int   getLivePeriod() Optional. Period in seconds for which the location can be updated, should be between 60 and 86400.
  *
- * @method $this setLatitude(float $latitude)   Latitude of the location in degrees
- * @method $this setLongitude(float $longitude) Longitude of the location in degrees
+ * @method $this setLatitude(float $latitude)    Latitude of the location in degrees
+ * @method $this setLongitude(float $longitude)  Longitude of the location in degrees
+ * @method $this setLivePeriod(int $live_period) Optional. Period in seconds for which the location can be updated, should be between 60 and 86400.
  */
 class InputLocationMessageContent extends InlineEntity implements InputMessageContent
 {

src/Entities/Message.php

@@ -66,6 +66,7 @@ class Message extends Entity
             'forward_from_chat'  => Chat::class,
             'reply_to_message'   => ReplyToMessage::class,
             'entities'           => MessageEntity::class,
+            'caption_entities'   => MessageEntity::class,
             'audio'              => Audio::class,
             'document'           => Document::class,
             'photo'              => PhotoSize::class,
@@ -158,6 +159,21 @@ class Message extends Entity
         return empty($pretty_array) ? null : $pretty_array;
     }
 
+    /**
+     * Optional. For messages with a caption, special entities like usernames, URLs, bot commands, etc. that appear in the caption
+     *
+     * This method overrides the default getCaptionEntities method
+     * and returns a nice array of MessageEntity objects.
+     *
+     * @return null|MessageEntity[]
+     */
+    public function getCaptionEntities()
+    {
+        $pretty_array = $this->makePrettyObjectArray(MessageEntity::class, 'caption_entities');
+
+        return empty($pretty_array) ? null : $pretty_array;
+    }
+
     /**
      * return the entire command like /echo or /echo@bot1 if specified
      *

src/Request.php

@@ -33,6 +33,8 @@ use Longman\TelegramBot\Exception\TelegramException;
  * @method static ServerResponse sendVoice(array $data)               Use this method to send audio files, if you want Telegram clients to display the file as a playable voice message. For this to work, your audio must be in an .ogg file encoded with OPUS (other formats may be sent as Audio or Document). On success, the sent Message is returned. Bots can currently send voice messages of up to 50 MB in size, this limit may be changed in the future.
  * @method static ServerResponse sendVideoNote(array $data)           Use this method to send video messages. On success, the sent Message is returned.
  * @method static ServerResponse sendLocation(array $data)            Use this method to send point on the map. On success, the sent Message is returned.
+ * @method static ServerResponse editMessageLiveLocation(array $data) Use this method to edit live location messages sent by the bot or via the bot (for inline bots). A location can be edited until its live_period expires or editing is explicitly disabled by a call to stopMessageLiveLocation. On success, if the edited message was sent by the bot, the edited Message is returned, otherwise True is returned.
+ * @method static ServerResponse stopMessageLiveLocation(array $data) Use this method to stop updating a live location message sent by the bot or via the bot (for inline bots) before live_period expires. On success, if the message was sent by the bot, the sent Message is returned, otherwise True is returned.
  * @method static ServerResponse sendVenue(array $data)               Use this method to send information about a venue. On success, the sent Message is returned.
  * @method static ServerResponse sendContact(array $data)             Use this method to send phone contacts. On success, the sent Message is returned.
  * @method static ServerResponse sendChatAction(array $data)          Use this method when you need to tell the user that something is happening on the bot's side. The status is set for 5 seconds or less (when a message arrives from your bot, Telegram clients clear its typing status). Returns True on success.
@@ -54,6 +56,8 @@ use Longman\TelegramBot\Exception\TelegramException;
  * @method static ServerResponse getChatAdministrators(array $data)   Use this method to get a list of administrators in a chat. On success, returns an Array of ChatMember objects that contains information about all chat administrators except other bots. If the chat is a group or a supergroup and no administrators were appointed, only the creator will be returned.
  * @method static ServerResponse getChatMembersCount(array $data)     Use this method to get the number of members in a chat. Returns Int on success.
  * @method static ServerResponse getChatMember(array $data)           Use this method to get information about a member of a chat. Returns a ChatMember object on success.
+ * @method static ServerResponse setChatStickerSet(array $data)       Use this method to set a new group sticker set for a supergroup. The bot must be an administrator in the chat for this to work and must have the appropriate admin rights. Use the field can_set_sticker_set optionally returned in getChat requests to check if the bot can use this method. Returns True on success.
+ * @method static ServerResponse deleteChatStickerSet(array $data)    Use this method to delete a group sticker set from a supergroup. The bot must be an administrator in the chat for this to work and must have the appropriate admin rights. Use the field can_set_sticker_set optionally returned in getChat requests to check if the bot can use this method. Returns True on success.
  * @method static ServerResponse answerCallbackQuery(array $data)     Use this method to send answers to callback queries sent from inline keyboards. The answer will be displayed to the user as a notification at the top of the chat screen or as an alert. On success, True is returned.
  * @method static ServerResponse answerInlineQuery(array $data)       Use this method to send answers to an inline query. On success, True is returned.
  * @method static ServerResponse editMessageText(array $data)         Use this method to edit text and game messages sent by the bot or via the bot (for inline bots). On success, if edited message is sent by the bot, the edited Message is returned, otherwise True is returned.
@@ -139,6 +143,8 @@ class Request
         'sendVoice',
         'sendVideoNote',
         'sendLocation',
+        'editMessageLiveLocation',
+        'stopMessageLiveLocation',
         'sendVenue',
         'sendContact',
         'sendChatAction',
@@ -160,6 +166,8 @@ class Request
         'getChatAdministrators',
         'getChatMembersCount',
         'getChatMember',
+        'setChatStickerSet',
+        'deleteChatStickerSet',
         'answerCallbackQuery',
         'answerInlineQuery',
         'editMessageText',
@@ -646,6 +654,8 @@ class Request
                 'sendVoice',
                 'sendVideoNote',
                 'sendLocation',
+                'editMessageLiveLocation',
+                'stopMessageLiveLocation',
                 'sendVenue',
                 'sendContact',
                 'sendInvoice',
@@ -654,6 +664,8 @@ class Request
                 'editMessageReplyMarkup',
                 'setChatTitle',
                 'setChatDescription',
+                'setChatStickerSet',
+                'deleteChatStickerSet',
             ];
 
             $chat_id           = isset($data['chat_id']) ? $data['chat_id'] : null;