Merge pull request #990 from noplanman/bot_api_4.4

Bot API 4.4 (Animated stickers, `ChatPermissions`)

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]
 ### Added
+- Bot API 4.4 (Animated stickers, `ChatPermissions`).
 ### Changed
 ### Deprecated
 ### Removed

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-4.3%20%28May%202019%29-32a2da.svg)](https://core.telegram.org/bots/api#may-31-2019)
+[![API Version](https://img.shields.io/badge/Bot%20API-4.4%20%28July%202019%29-32a2da.svg)](https://core.telegram.org/bots/api#july-29-2019)
 [![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)
 
@@ -74,7 +74,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 API 4.3 (May 2019).
+- Supports all types and methods according to Telegram API 4.4 (July 2019).
 - Supports supergroups.
 - Handle commands in chat with other bots.
 - Manage Channel from the bot admin interface.

src/Entities/Chat.php

@@ -15,31 +15,22 @@
  *
  * @link https://core.telegram.org/bots/api#chat
  *
- * @property int       $id                              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.
- * @property string    $type                            Type of chat, can be either "private", "group", "supergroup" or "channel"
- * @property string    $title                           Optional. Title, for channels and group chats
- * @property string    $username                        Optional. Username, for private chats, supergroups and channels if available
- * @property string    $first_name                      Optional. First name of the other party in a private chat
- * @property string    $last_name                       Optional. Last name of the other party in a private chat
- * @property bool      $all_members_are_administrators  Optional. True if a group has ‘All Members Are Admins’ enabled.
- * @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
- * @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      getAllMembersAreAdministrators() Optional. True if a group has ‘All Members Are Admins’ enabled.
- * @method   ChatPhoto getPhoto()                       Optional. Chat photo. Returned only in getChat.
- * @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.
+ * @property string type Type of chat, can be either "private ", "group", "supergroup" or "channel"
+ *
+ * @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
+ * @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            getAllMembersAreAdministrators() Optional. True if a group has ‘All Members Are Admins’ enabled. {@deprecated} {@see Chat::getPermissions()}
+ * @method   ChatPhoto       getPhoto()                       Optional. Chat photo. Returned only in getChat.
+ * @method   string          getDescription()                 Optional. Description, for groups, supergroups and channel chats. Returned only in getChat.
+ * @method   string          getInviteLink()                  Optional. Chat invite link, for groups, supergroups and channel chats. Each administrator in a chat generates their own invite links, so the bot must first generate the link using exportChatInviteLink. Returned only in getChat.
+ * @method   Message         getPinnedMessage()               Optional. Pinned message, for groups, supergroups and channels. Returned only in getChat.
+ * @method   ChatPermissions getPermissions()                 Optional. Default chat member permissions, for groups and 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 the group sticker set. Returned only in getChat.
  */
 class Chat extends Entity
 {
@@ -51,6 +42,7 @@ protected function subEntities()
         return [
             'photo'          => ChatPhoto::class,
             'pinned_message' => Message::class,
+            'permissions'    => ChatPermissions::class,
         ];
     }
 

src/Entities/ChatMember.php

@@ -19,17 +19,18 @@
  * @method string getStatus()                The member's status in the chat. Can be “creator”, “administrator”, “member”, “restricted”, “left” or “kicked”
  * @method int    getUntilDate()             Optional. Restricted and kicked only. Date when restrictions will be lifted for this user, unix time
  * @method bool   getCanBeEdited()           Optional. Administrators only. True, if the bot is allowed to edit administrator privileges of that user
- * @method bool   getCanChangeInfo()         Optional. Administrators only. True, if the administrator can change the chat title, photo and other settings
  * @method bool   getCanPostMessages()       Optional. Administrators only. True, if the administrator can post in the channel, channels only
  * @method bool   getCanEditMessages()       Optional. Administrators only. True, if the administrator can edit messages of other users, channels only
  * @method bool   getCanDeleteMessages()     Optional. Administrators only. True, if the administrator can delete messages of other users
- * @method bool   getCanInviteUsers()        Optional. Administrators only. True, if the administrator can invite new users to the chat
  * @method bool   getCanRestrictMembers()    Optional. Administrators only. True, if the administrator can restrict, ban or unban chat members
- * @method bool   getCanPinMessages()        Optional. Administrators only. True, if the administrator can pin messages, supergroups only
  * @method bool   getCanPromoteMembers()     Optional. Administrators only. True, if the administrator can add new administrators with a subset of his own privileges or demote administrators that he has promoted, directly or indirectly (promoted by administrators that were appointed by the user)
+ * @method bool   getCanChangeInfo()         Optional. Administrators and restricted only. True, if the user is allowed to change the chat title, photo and other settings
+ * @method bool   getCanInviteUsers()        Optional. Administrators and restricted only. True, if the user is allowed to invite new users to the chat
+ * @method bool   getCanPinMessages()        Optional. Administrators and restricted only. True, if the user is allowed to pin messages; groups and supergroups only
  * @method bool   getIsMember()              Optional. Restricted only. True, if the user is a member of the chat at the moment of the request
  * @method bool   getCanSendMessages()       Optional. Restricted only. True, if the user can send text messages, contacts, locations and venues
  * @method bool   getCanSendMediaMessages()  Optional. Restricted only. True, if the user can send audios, documents, photos, videos, video notes and voice notes, implies can_send_messages
+ * @method bool   getCanSendPolls()          Optional. Restricted only. True, if the user is allowed to send polls
  * @method bool   getCanSendOtherMessages()  Optional. Restricted only. True, if the user can send animations, games, stickers and use inline bots, implies can_send_media_messages
  * @method bool   getCanAddWebPagePreviews() Optional. Restricted only. True, if user may add web page previews to his messages, implies can_send_media_messages
  */

src/Entities/ChatPermissions.php

@@ -0,0 +1,30 @@
+<?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 ChatPermissions
+ *
+ * @link https://core.telegram.org/bots/api#chatpermissions
+ *
+ * @method bool getCanSendMessages()       Optional. True, if the user is allowed to send text messages, contacts, locations and venues
+ * @method bool getCanSendMediaMessages()  Optional. True, if the user is allowed to send audios, documents, photos, videos, video notes and voice notes, implies can_send_messages
+ * @method bool getCanSendPolls()          Optional. True, if the user is allowed to send polls, implies can_send_messages
+ * @method bool getCanSendOtherMessages()  Optional. True, if the user is allowed to send animations, games, stickers and use inline bots, implies can_send_media_messages
+ * @method bool getCanAddWebPagePreviews() Optional. True, if the user is allowed to add web page previews to their messages, implies can_send_media_messages
+ * @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
+ */
+class ChatPermissions extends Entity
+{
+
+}

src/Entities/ChatPhoto.php

@@ -15,8 +15,8 @@
  *
  * @link https://core.telegram.org/bots/api#chatphoto
  *
- * @method string getSmallFileId() Unique file identifier of small(160x160) chat photo. This file_id can be used only for photo download.
- * @method string getBigFileId()   Unique file identifier of big(640x640) chat photo. This file_id can be used only for photo download.
+ * @method string getSmallFileId() Unique file identifier of small (160x160) chat photo. This file_id can be used only for photo download and only for as long as the photo is not changed.
+ * @method string getBigFileId()   Unique file identifier of big (640x640) chat photo. This file_id can be used only for photo download and only for as long as the photo is not changed.
  */
 class ChatPhoto extends Entity
 {

src/Entities/Sticker.php

@@ -18,6 +18,7 @@
  * @method string       getFileId()       Unique identifier for this file
  * @method int          getWidth()        Sticker width
  * @method int          getHeight()       Sticker height
+ * @method bool         getIsAnimated()   True, if the sticker is animated
  * @method PhotoSize    getThumb()        Optional. Sticker thumbnail in .webp or .jpg format
  * @method string       getEmoji()        Optional. Emoji associated with the sticker
  * @method string       getSetName()      Optional. Name of the sticker set to which the sticker belongs

src/Entities/StickerSet.php

@@ -17,6 +17,7 @@
  *
  * @method string    getName()          Sticker set name
  * @method string    getTitle()         Sticker set title
+ * @method bool      getIsAnimated()    True, if the sticker set contains animated stickers
  * @method bool      getContainsMasks() True, if the sticker set contains masks
  * @method Sticker[] getStickers()      List of all set stickers
  */

src/Request.php

@@ -48,13 +48,14 @@
  * @method static ServerResponse getFile(array $data)                 Use this method to get basic info about a file and prepare it for downloading. For the moment, bots can download files of up to 20MB in size. On success, a File object is returned. The file can then be downloaded via the link https://api.telegram.org/file/bot<token>/<file_path>, where <file_path> is taken from the response. It is guaranteed that the link will be valid for at least 1 hour. When the link expires, a new one can be requested by calling getFile again.
  * @method static ServerResponse kickChatMember(array $data)          Use this method to kick a user from a group, a supergroup or a channel. In the case of supergroups and channels, the user will not be able to return to the group on their own using invite links, etc., unless unbanned first. 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 unbanChatMember(array $data)         Use this method to unban a previously kicked user in a supergroup or channel. The user will not return to the group or channel automatically, but will be able to join via link, etc. The bot must be an administrator for this to work. Returns True on success.
- * @method static ServerResponse restrictChatMember(array $data)      Use this method to restrict a user in a supergroup. The bot must be an administrator in the supergroup for this to work and must have the appropriate admin rights. Pass True for all boolean parameters to lift restrictions from a user. Returns True on success.
+ * @method static ServerResponse restrictChatMember(array $data)      Use this method to restrict a user in a supergroup. The bot must be an administrator in the supergroup for this to work and must have the appropriate admin rights. Pass True for all permissions to lift restrictions from a user. Returns True on success.
  * @method static ServerResponse promoteChatMember(array $data)       Use this method to promote or demote a user in a supergroup or a channel. The bot must be an administrator in the chat for this to work and must have the appropriate admin rights. Pass False for all boolean parameters to demote a user. Returns True on success.
- * @method static ServerResponse exportChatInviteLink(array $data)    Use this method to export an invite link to a supergroup or a channel. The bot must be an administrator in the chat for this to work and must have the appropriate admin rights. Returns exported invite link as String on success.
+ * @method static ServerResponse setChatPermissions(array $data)      Use this method to set default chat permissions for all members. The bot must be an administrator in the group or a supergroup for this to work and must have the can_restrict_members admin rights. Returns True on success.
+ * @method static ServerResponse exportChatInviteLink(array $data)    Use this method to generate a new invite link for a chat; any previously generated link is revoked. The bot must be an administrator in the chat for this to work and must have the appropriate admin rights. Returns the new invite link as String 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.
- * @method static ServerResponse setChatDescription(array $data)      Use this method to change the description of a supergroup or a channel. 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 setChatDescription(array $data)      Use this method to change the description of a group, a supergroup or a channel. 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 pinChatMessage(array $data)          Use this method to pin a message in a supergroup or a channel. The bot must be an administrator in the chat for this to work and must have the ‘can_pin_messages’ admin right in the supergroup or ‘can_edit_messages’ admin right in the channel. Returns True on success.
  * @method static ServerResponse unpinChatMessage(array $data)        Use this method to unpin a message in a supergroup or a channel. The bot must be an administrator in the chat for this to work and must have the ‘can_pin_messages’ admin right in the supergroup or ‘can_edit_messages’ admin right in the channel. Returns True on success.
  * @method static ServerResponse leaveChat(array $data)               Use this method for your bot to leave a group, supergroup or channel. Returns True on success.
@@ -176,6 +177,7 @@ class Request
         'unbanChatMember',
         'restrictChatMember',
         'promoteChatMember',
+        'setChatPermissions',
         'exportChatInviteLink',
         'setChatPhoto',
         'deleteChatPhoto',