Merge pull request #1046 from noplanman/1038-bot_api_4.5

noplanman · web-flow · commit 62dad0a4dc07 · 2020-01-28T22:32:20.000+01:00
Bot API 4.5
diff --git a/CHANGELOG.md b/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.5 (Unique file IDs, MarkdownV2).
 ### Changed
 ### Deprecated
 ### Removed
diff --git a/README.md b/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.4%20%28July%202019%29-32a2da.svg)](https://core.telegram.org/bots/api#july-29-2019)
+[![API Version](https://img.shields.io/badge/Bot%20API-4.5%20%28December%202019%29-32a2da.svg)](https://core.telegram.org/bots/api#december-31-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)
 
diff --git a/src/Entities/Animation.php b/src/Entities/Animation.php
@@ -18,14 +18,15 @@
  *
  * @link https://core.telegram.org/bots/api#animation
  *
- * @method string    getFileId()   Unique file identifier
- * @method int       getWidth()    Video width as defined by sender
- * @method int       getHeight()   Video height as defined by sender
- * @method int       getDuration() Duration of the video in seconds as defined by sender
- * @method PhotoSize getThumb()    Optional. Animation thumbnail as defined by sender
- * @method string    getFileName() Optional. Original animation filename as defined by sender
- * @method string    getMimeType() Optional. MIME type of the file as defined by sender
- * @method int       getFileSize() Optional. File size
+ * @method string    getFileId()       Identifier for this file, which can be used to download or reuse the file
+ * @method string    getFileUniqueId() Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file.
+ * @method int       getWidth()        Video width as defined by sender
+ * @method int       getHeight()       Video height as defined by sender
+ * @method int       getDuration()     Duration of the video in seconds as defined by sender
+ * @method PhotoSize getThumb()        Optional. Animation thumbnail as defined by sender
+ * @method string    getFileName()     Optional. Original animation filename as defined by sender
+ * @method string    getMimeType()     Optional. MIME type of the file as defined by sender
+ * @method int       getFileSize()     Optional. File size
  **/
 class Animation extends Entity
 {
diff --git a/src/Entities/Audio.php b/src/Entities/Audio.php
@@ -16,13 +16,14 @@
  *
  * @link https://core.telegram.org/bots/api#audio
  *
- * @method string    getFileId()    Unique identifier for this file
- * @method int       getDuration()  Duration of the audio in seconds as defined by sender
- * @method string    getPerformer() Optional. Performer of the audio as defined by sender or by audio tags
- * @method string    getTitle()     Optional. Title of the audio as defined by sender or by audio tags
- * @method string    getMimeType()  Optional. MIME type of the file as defined by sender
- * @method int       getFileSize()  Optional. File size
- * @method PhotoSize getThumb()     Optional. Thumbnail of the album cover to which the music file belongs
+ * @method string    getFileId()       Identifier for this file, which can be used to download or reuse the file
+ * @method string    getFileUniqueId() Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file.
+ * @method int       getDuration()     Duration of the audio in seconds as defined by sender
+ * @method string    getPerformer()    Optional. Performer of the audio as defined by sender or by audio tags
+ * @method string    getTitle()        Optional. Title of the audio as defined by sender or by audio tags
+ * @method string    getMimeType()     Optional. MIME type of the file as defined by sender
+ * @method int       getFileSize()     Optional. File size
+ * @method PhotoSize getThumb()        Optional. Thumbnail of the album cover to which the music file belongs
  */
 class Audio extends Entity
 {
diff --git a/src/Entities/Chat.php b/src/Entities/Chat.php
@@ -18,20 +18,21 @@
  *
  * @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.
+ * @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 int             getSlowModeDelay()               Optional. For supergroups, the minimum allowed delay between consecutive messages sent by each unpriviledged user. 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
 {
diff --git a/src/Entities/ChatMember.php b/src/Entities/ChatMember.php
@@ -18,6 +18,7 @@
  *
  * @method User   getUser()                  Information about the user
  * @method string getStatus()                The member's status in the chat. Can be “creator”, “administrator”, “member”, “restricted”, “left” or “kicked”
+ * @method string getCustomTitle()           Optional. Owner and administrators only. Custom title for this user
  * @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   getCanPostMessages()       Optional. Administrators only. True, if the administrator can post in the channel, channels only
diff --git a/src/Entities/ChatPhoto.php b/src/Entities/ChatPhoto.php
@@ -16,8 +16,10 @@
  *
  * @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 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.
+ * @method string getSmallFileId()       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 getSmallFileUniqueId() Unique file identifier of small (160x160) chat photo, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file.
+ * @method string getBigFileId()         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.
+ * @method string getBigFileUniqueId()   Unique file identifier of big (640x640) chat photo, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file.
  */
 class ChatPhoto extends Entity
 {
diff --git a/src/Entities/Document.php b/src/Entities/Document.php
@@ -16,11 +16,12 @@
  *
  * @link https://core.telegram.org/bots/api#document
  *
- * @method string    getFileId()   Unique file identifier
- * @method PhotoSize getThumb()    Optional. Document thumbnail as defined by sender
- * @method string    getFileName() Optional. Original filename as defined by sender
- * @method string    getMimeType() Optional. MIME type of the file as defined by sender
- * @method int       getFileSize() Optional. File size
+ * @method string    getFileId()       Identifier for this file, which can be used to download or reuse the file
+ * @method string    getFileUniqueId() Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file.
+ * @method PhotoSize getThumb()        Optional. Document thumbnail as defined by sender
+ * @method string    getFileName()     Optional. Original filename as defined by sender
+ * @method string    getMimeType()     Optional. MIME type of the file as defined by sender
+ * @method int       getFileSize()     Optional. File size
  */
 class Document extends Entity
 {
diff --git a/src/Entities/File.php b/src/Entities/File.php
@@ -16,9 +16,10 @@
  *
  * @link https://core.telegram.org/bots/api#file
  *
- * @method string getFileId()   Unique identifier for this file
- * @method int    getFileSize() Optional. File size, if known
- * @method string getFilePath() Optional. File path. Use https://api.telegram.org/file/bot<token>/<file_path> to get the file.
+ * @method string getFileId()       Identifier for this file, which can be used to download or reuse the file
+ * @method string getFileUniqueId() Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file.
+ * @method int    getFileSize()     Optional. File size, if known
+ * @method string getFilePath()     Optional. File path. Use https://api.telegram.org/file/bot<token>/<file_path> to get the file.
  */
 class File extends Entity
 {
diff --git a/src/Entities/MessageEntity.php b/src/Entities/MessageEntity.php
@@ -16,7 +16,7 @@
  *
  * @link https://core.telegram.org/bots/api#messageentity
  *
- * @method string getType()   Type of the entity. Can be mention (@username), hashtag, cashtag, bot_command, url, email, phone_number, bold (bold text), italic (italic text), code (monowidth string), pre (monowidth block), text_link (for clickable text URLs), text_mention (for users without usernames)
+ * @method string getType()   Type of the entity. Can be 'mention' (@username), 'hashtag' (#hashtag), 'cashtag' ($USD), 'bot_command' (/start@jobs_bot), 'url' (https://telegram.org), 'email' (do-not-reply@telegram.org), 'phone_number' (+1-212-555-0123), 'bold' (bold text), 'italic' (italic text), 'underline' (underlined text), 'strikethrough' (strikethrough text), 'code' (monowidth string), 'pre' (monowidth block), 'text_link' (for clickable text URLs), 'text_mention' (for users without usernames)
  * @method int    getOffset() Offset in UTF-16 code units to the start of the entity
  * @method int    getLength() Length of the entity in UTF-16 code units
  * @method string getUrl()    Optional. For "text_link" only, url that will be opened after user taps on the text
diff --git a/src/Entities/PhotoSize.php b/src/Entities/PhotoSize.php
@@ -16,10 +16,11 @@
  *
  * @link https://core.telegram.org/bots/api#photosize
  *
- * @method string getFileId()   Unique identifier for this file
- * @method int    getWidth()    Photo width
- * @method int    getHeight()   Photo height
- * @method int    getFileSize() Optional. File size
+ * @method string getFileId()       Identifier for this file, which can be used to download or reuse the file
+ * @method string getFileUniqueId() Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file.
+ * @method int    getWidth()        Photo width
+ * @method int    getHeight()       Photo height
+ * @method int    getFileSize()     Optional. File size
  */
 class PhotoSize extends Entity
 {
diff --git a/src/Entities/Sticker.php b/src/Entities/Sticker.php
@@ -16,7 +16,8 @@
  *
  * @link https://core.telegram.org/bots/api#sticker
  *
- * @method string       getFileId()       Unique identifier for this file
+ * @method string       getFileId()       Identifier for this file, which can be used to download or reuse the file
+ * @method string       getFileUniqueId() Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file.
  * @method int          getWidth()        Sticker width
  * @method int          getHeight()       Sticker height
  * @method bool         getIsAnimated()   True, if the sticker is animated
diff --git a/src/Entities/TelegramPassport/PassportFile.php b/src/Entities/TelegramPassport/PassportFile.php
@@ -20,9 +20,10 @@
  *
  * @link https://core.telegram.org/bots/api#passportfile
  *
- * @method string getFileId()   Unique identifier for this file
- * @method int    getFileSize() File size
- * @method int    getFileDate() Unix time when the file was uploaded
+ * @method string getFileId()       Identifier for this file, which can be used to download or reuse the file
+ * @method string getFileUniqueId() Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file.
+ * @method int    getFileSize()     File size
+ * @method int    getFileDate()     Unix time when the file was uploaded
  **/
 class PassportFile extends Entity
 {
diff --git a/src/Entities/Video.php b/src/Entities/Video.php
@@ -16,13 +16,14 @@
  *
  * @link https://core.telegram.org/bots/api#video
  *
- * @method string    getFileId()   Unique identifier for this file
- * @method int       getWidth()    Video width as defined by sender
- * @method int       getHeight()   Video height as defined by sender
- * @method int       getDuration() Duration of the video in seconds as defined by sender
- * @method PhotoSize getThumb()    Optional. Video thumbnail
- * @method string    getMimeType() Optional. Mime type of a file as defined by sender
- * @method int       getFileSize() Optional. File size
+ * @method string    getFileId()       Identifier for this file, which can be used to download or reuse the file
+ * @method string    getFileUniqueId() Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file.
+ * @method int       getWidth()        Video width as defined by sender
+ * @method int       getHeight()       Video height as defined by sender
+ * @method int       getDuration()     Duration of the video in seconds as defined by sender
+ * @method PhotoSize getThumb()        Optional. Video thumbnail
+ * @method string    getMimeType()     Optional. Mime type of a file as defined by sender
+ * @method int       getFileSize()     Optional. File size
  */
 class Video extends Entity
 {
diff --git a/src/Entities/VideoNote.php b/src/Entities/VideoNote.php
@@ -16,11 +16,12 @@
  *
  * @link https://core.telegram.org/bots/api#videonote
  *
- * @method string    getFileId()   Unique identifier for this file
- * @method int       getLength()   Video width and height as defined by sender
- * @method int       getDuration() Duration of the audio in seconds as defined by sender
- * @method PhotoSize getThumb()    Optional. Video thumbnail as defined by sender
- * @method int       getFileSize() Optional. File size
+ * @method string    getFileId()       Identifier for this file, which can be used to download or reuse the file
+ * @method string    getFileUniqueId() Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file.
+ * @method int       getLength()       Video width and height as defined by sender
+ * @method int       getDuration()     Duration of the audio in seconds as defined by sender
+ * @method PhotoSize getThumb()        Optional. Video thumbnail as defined by sender
+ * @method int       getFileSize()     Optional. File size
  */
 class VideoNote extends Entity
 {
diff --git a/src/Entities/Voice.php b/src/Entities/Voice.php
@@ -16,10 +16,11 @@
  *
  * @link https://core.telegram.org/bots/api#voice
  *
- * @method string getFileId()   Unique identifier for this file
- * @method int    getDuration() Duration of the audio in seconds as defined by sender
- * @method string getMimeType() Optional. MIME type of the file as defined by sender
- * @method int    getFileSize() Optional. File size
+ * @method string getFileId()       Identifier for this file, which can be used to download or reuse the file
+ * @method string getFileUniqueId() Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file.
+ * @method int    getDuration()     Duration of the audio in seconds as defined by sender
+ * @method string getMimeType()     Optional. MIME type of the file as defined by sender
+ * @method int    getFileSize()     Optional. File size
  */
 class Voice extends Entity
 {
diff --git a/src/Request.php b/src/Request.php

Original file line number	Diff line number	Diff line change
`@@ -18,6 +18,7 @@`
`18`	`18`	`*`
`19`	`19`	`* @method User getUser() Information about the user`
`20`	`20`	`* @method string getStatus() The member's status in the chat. Can be “creator”, “administrator”, “member”, “restricted”, “left” or “kicked”`
	`21`	`+ * @method string getCustomTitle() Optional. Owner and administrators only. Custom title for this user`
`21`	`22`	`* @method int getUntilDate() Optional. Restricted and kicked only. Date when restrictions will be lifted for this user, unix time`
`22`	`23`	`* @method bool getCanBeEdited() Optional. Administrators only. True, if the bot is allowed to edit administrator privileges of that user`
`23`	`24`	`* @method bool getCanPostMessages() Optional. Administrators only. True, if the administrator can post in the channel, channels only`
Original file line number	Diff line number	Diff line change
`@@ -16,8 +16,10 @@`
`16`	`16`	`*`
`17`	`17`	`* @link https://core.telegram.org/bots/api#chatphoto`
`18`	`18`	`*`
`19`		`- * @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.`
`20`		`- * @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.`
	`19`	`+ * @method string getSmallFileId() 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.`
	`20`	`+ * @method string getSmallFileUniqueId() Unique file identifier of small (160x160) chat photo, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file.`
	`21`	`+ * @method string getBigFileId() 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.`
	`22`	`+ * @method string getBigFileUniqueId() Unique file identifier of big (640x640) chat photo, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file.`
`21`	`23`	`*/`
`22`	`24`	`class ChatPhoto extends Entity`
`23`	`25`	`{`
Original file line number	Diff line number	Diff line change
`@@ -16,11 +16,12 @@`
`16`	`16`	`*`
`17`	`17`	`* @link https://core.telegram.org/bots/api#document`
`18`	`18`	`*`
`19`		`- * @method string getFileId() Unique file identifier`
`20`		`- * @method PhotoSize getThumb() Optional. Document thumbnail as defined by sender`
`21`		`- * @method string getFileName() Optional. Original filename as defined by sender`
`22`		`- * @method string getMimeType() Optional. MIME type of the file as defined by sender`
`23`		`- * @method int getFileSize() Optional. File size`
	`19`	`+ * @method string getFileId() Identifier for this file, which can be used to download or reuse the file`
	`20`	`+ * @method string getFileUniqueId() Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file.`
	`21`	`+ * @method PhotoSize getThumb() Optional. Document thumbnail as defined by sender`
	`22`	`+ * @method string getFileName() Optional. Original filename as defined by sender`
	`23`	`+ * @method string getMimeType() Optional. MIME type of the file as defined by sender`
	`24`	`+ * @method int getFileSize() Optional. File size`
`24`	`25`	`*/`
`25`	`26`	`class Document extends Entity`
`26`	`27`	`{`
Original file line number	Diff line number	Diff line change
`@@ -16,9 +16,10 @@`
`16`	`16`	`*`
`17`	`17`	`* @link https://core.telegram.org/bots/api#file`
`18`	`18`	`*`
`19`		`- * @method string getFileId() Unique identifier for this file`
`20`		`- * @method int getFileSize() Optional. File size, if known`
`21`		`- * @method string getFilePath() Optional. File path. Use https://api.telegram.org/file/bot<token>/<file_path> to get the file.`
	`19`	`+ * @method string getFileId() Identifier for this file, which can be used to download or reuse the file`
	`20`	`+ * @method string getFileUniqueId() Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file.`
	`21`	`+ * @method int getFileSize() Optional. File size, if known`
	`22`	`+ * @method string getFilePath() Optional. File path. Use https://api.telegram.org/file/bot<token>/<file_path> to get the file.`
`22`	`23`	`*/`
`23`	`24`	`class File extends Entity`
`24`	`25`	`{`
Original file line number	Diff line number	Diff line change
`@@ -16,7 +16,7 @@`
`16`	`16`	`*`
`17`	`17`	`* @link https://core.telegram.org/bots/api#messageentity`
`18`	`18`	`*`
`19`		`- * @method string getType() Type of the entity. Can be mention (@username), hashtag, cashtag, bot_command, url, email, phone_number, bold (bold text), italic (italic text), code (monowidth string), pre (monowidth block), text_link (for clickable text URLs), text_mention (for users without usernames)`
	`19`	`+ * @method string getType() Type of the entity. Can be 'mention' (@username), 'hashtag' (#hashtag), 'cashtag' ($USD), 'bot_command' (/start@jobs_bot), 'url' (https://telegram.org), 'email' ([email protected]), 'phone_number' (+1-212-555-0123), 'bold' (bold text), 'italic' (italic text), 'underline' (underlined text), 'strikethrough' (strikethrough text), 'code' (monowidth string), 'pre' (monowidth block), 'text_link' (for clickable text URLs), 'text_mention' (for users without usernames)`
`20`	`20`	`* @method int getOffset() Offset in UTF-16 code units to the start of the entity`
`21`	`21`	`* @method int getLength() Length of the entity in UTF-16 code units`
`22`	`22`	`* @method string getUrl() Optional. For "text_link" only, url that will be opened after user taps on the text`