From 57255e68469fa6c9331cd0f5d536bd333566345b Mon Sep 17 00:00:00 2001 From: Camilo Sperberg Date: Sun, 8 Jan 2017 01:25:11 +0100 Subject: [PATCH] General update on documentation Also fixes some bugs (See #18 and #17) and other bugs that had not been detected before. Also some micro-optimizations --- src/Abstracts/TelegramMethods.php | 13 +++++++ src/Abstracts/TelegramTypes.php | 6 ++-- src/Telegram/Methods/AnswerCallbackQuery.php | 6 +++- src/Telegram/Methods/EditMessageCaption.php | 21 ++++++++++- .../Methods/EditMessageReplyMarkup.php | 21 ++++++++++- src/Telegram/Methods/EditMessageText.php | 21 ++++++++++- src/Telegram/Methods/GetUpdates.php | 18 +++------- src/Telegram/Methods/SendAudio.php | 12 ++++--- src/Telegram/Methods/SendChatAction.php | 9 +++++ src/Telegram/Methods/SendContact.php | 5 +-- src/Telegram/Methods/SendDocument.php | 18 +++++----- src/Telegram/Methods/SendLocation.php | 5 +-- src/Telegram/Methods/SendMessage.php | 2 +- src/Telegram/Methods/SendPhoto.php | 16 +++++---- src/Telegram/Methods/SendSticker.php | 16 +++++---- src/Telegram/Methods/SendVenue.php | 5 +-- src/Telegram/Methods/SendVideo.php | 18 +++++----- src/Telegram/Methods/SendVoice.php | 18 +++++----- src/Telegram/Methods/SetWebhook.php | 12 ++++--- src/Telegram/Types/Animation.php | 4 +-- src/Telegram/Types/CallbackQuery.php | 10 ++++-- src/Telegram/Types/ChatMember.php | 2 +- .../Custom/InlineKeyboardButtonArray.php | 6 ++-- .../Types/Custom/KeyboardButtonArray.php | 6 ++-- src/Telegram/Types/Document.php | 2 +- src/Telegram/Types/Inline/ChosenResult.php | 8 ++--- src/Telegram/Types/Inline/Keyboard/Markup.php | 2 +- src/Telegram/Types/Inline/Query.php | 8 ++--- src/Telegram/Types/Inline/Query/Result.php | 5 +-- .../Inline/Query/Result/Cached/Sticker.php | 2 +- src/Telegram/Types/KeyboardButton.php | 4 ++- src/Telegram/Types/Message.php | 36 +++++++++---------- src/Telegram/Types/MessageEntity.php | 2 +- src/Telegram/Types/ReplyKeyboardMarkup.php | 2 +- src/Telegram/Types/Sticker.php | 3 +- src/Telegram/Types/Update.php | 16 ++++----- src/Telegram/Types/UserProfilePhotos.php | 2 +- src/Telegram/Types/Venue.php | 2 +- src/Telegram/Types/Video.php | 5 ++- src/Telegram/Types/WebhookInfo.php | 12 +++++++ src/TgLog.php | 4 +-- tests/Telegram/Methods/SetWebhookTest.php | 11 ++++++ 42 files changed, 255 insertions(+), 141 deletions(-) diff --git a/src/Abstracts/TelegramMethods.php b/src/Abstracts/TelegramMethods.php index 0c3b83d..babd5e1 100644 --- a/src/Abstracts/TelegramMethods.php +++ b/src/Abstracts/TelegramMethods.php @@ -48,6 +48,19 @@ public function performSpecialConditions(): TelegramMethods $this->reply_markup = json_encode($this->reply_markup); } + // Several classes may send a parse mode, so check before sending + // TODO Do I want to validate data in here? Should I? + /* + * if (!empty($this->parse_mode)) { + if (strtoupper($this->parse_mode) !== 'HTML' || strtoupper($this->parse_mode) !== 'MARKDOWN') { + throw new InvalidParseMode(sprintf( + 'An invalid value for parse_mode has been given. Please use HTML or Markdown. Provided: "%s"', + $this->parse_mode + )); + } + } + */ + return $this; } diff --git a/src/Abstracts/TelegramTypes.php b/src/Abstracts/TelegramTypes.php index 69199f5..ecab273 100644 --- a/src/Abstracts/TelegramTypes.php +++ b/src/Abstracts/TelegramTypes.php @@ -10,16 +10,16 @@ abstract class TelegramTypes { - protected $logger = null; + protected $logger; public function __construct(array $data = null, LoggerInterface $logger = null) { - if (is_null($logger)) { + if ($logger === null) { $logger = new DummyLogger(); } $this->logger = $logger; - if (!is_null($data)) { + if ($data !== null) { $this->populateObject($data); } } diff --git a/src/Telegram/Methods/AnswerCallbackQuery.php b/src/Telegram/Methods/AnswerCallbackQuery.php index 117c8e0..25f1c1a 100644 --- a/src/Telegram/Methods/AnswerCallbackQuery.php +++ b/src/Telegram/Methods/AnswerCallbackQuery.php @@ -14,7 +14,11 @@ * 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. * - * Objects defined as-is july 2016 + * Alternatively, the user can be redirected to the specified Game URL. For this option to work, you must first create a + * game for your bot via BotFather and accept the terms. Otherwise, you may use links like + * telegram.me/your_bot?start=XXXX that open your bot with a parameter + * + * Objects defined as-is January 2017 * * @see https://core.telegram.org/bots/api#answercallbackquery */ diff --git a/src/Telegram/Methods/EditMessageCaption.php b/src/Telegram/Methods/EditMessageCaption.php index 58d38fa..fea4c3c 100644 --- a/src/Telegram/Methods/EditMessageCaption.php +++ b/src/Telegram/Methods/EditMessageCaption.php @@ -4,8 +4,14 @@ namespace unreal4u\TelegramAPI\Telegram\Methods; +use Psr\Log\LoggerInterface; use unreal4u\TelegramAPI\Abstracts\TelegramMethods; +use unreal4u\TelegramAPI\Abstracts\TelegramTypes; +use unreal4u\TelegramAPI\Exceptions\InvalidResultType; +use unreal4u\TelegramAPI\InternalFunctionality\TelegramRawData; +use unreal4u\TelegramAPI\Telegram\Types\Custom\ResultBoolean; use unreal4u\TelegramAPI\Telegram\Types\Inline\Keyboard\Markup; +use unreal4u\TelegramAPI\Telegram\Types\Message; /** * Use this method to edit captions of messages sent by the bot or via the bot (for inline bots). On success, if edited @@ -46,11 +52,24 @@ class EditMessageCaption extends TelegramMethods * Optional. A JSON-serialized object for an inline keyboard. * @var Markup */ - public $reply_markup = null; + public $reply_markup; public function getMandatoryFields(): array { $returnValue = []; return $this->mandatoryUserOrInlineMessageId($returnValue); } + + public static function bindToObject(TelegramRawData $data, LoggerInterface $logger): TelegramTypes + { + $typeOfResult = $data->getTypeOfResult(); + switch ($typeOfResult) { + case 'array': + return new Message($data->getResult(), $logger); + case 'boolean': + return new ResultBoolean($data->getResultBoolean(), $logger); + default: + throw new InvalidResultType('Result is of type: %s. Expecting one of array or boolean'); + } + } } diff --git a/src/Telegram/Methods/EditMessageReplyMarkup.php b/src/Telegram/Methods/EditMessageReplyMarkup.php index 814e076..f0fa15e 100644 --- a/src/Telegram/Methods/EditMessageReplyMarkup.php +++ b/src/Telegram/Methods/EditMessageReplyMarkup.php @@ -4,8 +4,14 @@ namespace unreal4u\TelegramAPI\Telegram\Methods; +use Psr\Log\LoggerInterface; use unreal4u\TelegramAPI\Abstracts\TelegramMethods; +use unreal4u\TelegramAPI\Abstracts\TelegramTypes; +use unreal4u\TelegramAPI\Exceptions\InvalidResultType; +use unreal4u\TelegramAPI\InternalFunctionality\TelegramRawData; +use unreal4u\TelegramAPI\Telegram\Types\Custom\ResultBoolean; use unreal4u\TelegramAPI\Telegram\Types\Inline\Keyboard\Markup; +use unreal4u\TelegramAPI\Telegram\Types\Message; /** * Use this method to edit only the reply markup of messages sent by the bot or via the bot (for inline bots). On @@ -40,11 +46,24 @@ class EditMessageReplyMarkup extends TelegramMethods * Optional. A JSON-serialized object for an inline keyboard. * @var Markup */ - public $reply_markup = null; + public $reply_markup; public function getMandatoryFields(): array { $returnValue = []; return $this->mandatoryUserOrInlineMessageId($returnValue); } + + public static function bindToObject(TelegramRawData $data, LoggerInterface $logger): TelegramTypes + { + $typeOfResult = $data->getTypeOfResult(); + switch ($typeOfResult) { + case 'array': + return new Message($data->getResult(), $logger); + case 'boolean': + return new ResultBoolean($data->getResultBoolean(), $logger); + default: + throw new InvalidResultType('Result is of type: %s. Expecting one of array or boolean'); + } + } } diff --git a/src/Telegram/Methods/EditMessageText.php b/src/Telegram/Methods/EditMessageText.php index cafea15..701e043 100644 --- a/src/Telegram/Methods/EditMessageText.php +++ b/src/Telegram/Methods/EditMessageText.php @@ -4,8 +4,14 @@ namespace unreal4u\TelegramAPI\Telegram\Methods; +use Psr\Log\LoggerInterface; use unreal4u\TelegramAPI\Abstracts\TelegramMethods; +use unreal4u\TelegramAPI\Abstracts\TelegramTypes; +use unreal4u\TelegramAPI\Exceptions\InvalidResultType; +use unreal4u\TelegramAPI\InternalFunctionality\TelegramRawData; +use unreal4u\TelegramAPI\Telegram\Types\Custom\ResultBoolean; use unreal4u\TelegramAPI\Telegram\Types\Inline\Keyboard\Markup; +use unreal4u\TelegramAPI\Telegram\Types\Message; /** * Use this method to edit text messages sent by the bot or via the bot (for inline bots). On success, if edited message @@ -59,7 +65,7 @@ class EditMessageText extends TelegramMethods * Optional. A JSON-serialized object for an inline keyboard. * @var Markup */ - public $reply_markup = null; + public $reply_markup; public function getMandatoryFields(): array { @@ -67,4 +73,17 @@ public function getMandatoryFields(): array $this->mandatoryUserOrInlineMessageId($returnValue); return $returnValue; } + + public static function bindToObject(TelegramRawData $data, LoggerInterface $logger): TelegramTypes + { + $typeOfResult = $data->getTypeOfResult(); + switch ($typeOfResult) { + case 'array': + return new Message($data->getResult(), $logger); + case 'boolean': + return new ResultBoolean($data->getResultBoolean(), $logger); + default: + throw new InvalidResultType('Result is of type: %s. Expecting one of array or boolean'); + } + } } diff --git a/src/Telegram/Methods/GetUpdates.php b/src/Telegram/Methods/GetUpdates.php index e7bc7fa..7f59023 100644 --- a/src/Telegram/Methods/GetUpdates.php +++ b/src/Telegram/Methods/GetUpdates.php @@ -11,19 +11,9 @@ use unreal4u\TelegramAPI\Telegram\Types\Custom\UpdatesArray; /** - * This will get the updates Telegram has for our bot + * Use this method to receive incoming updates using long polling (wiki). An Array of Update objects is returned * - * This will work under 3 conditions: - * - * - * - * You can use this method to get the channel id the bot has to send messages to - * - * Objects defined as-is December 2016 + * Objects defined as-is January 2017 * * @see https://core.telegram.org/bots/api#getupdates */ @@ -32,7 +22,9 @@ class GetUpdates extends TelegramMethods /** * Identifier of the first update to be returned. Must be greater by one than the highest among the identifiers of * previously received updates. By default, updates starting with the earliest unconfirmed update are returned. An - * update is considered confirmed as soon as getUpdates is called with an offset higher than its update_id. + * update is considered confirmed as soon as getUpdates is called with an offset higher than its update_id. The + * negative offset can be specified to retrieve updates starting from -offset update from the end of the updates + * queue. All previous updates will forgotten * @var int */ public $offset = 0; diff --git a/src/Telegram/Methods/SendAudio.php b/src/Telegram/Methods/SendAudio.php index 2c5656d..527707d 100644 --- a/src/Telegram/Methods/SendAudio.php +++ b/src/Telegram/Methods/SendAudio.php @@ -17,7 +17,7 @@ * .ogg file encoded with OPUS. This behavior will be phased out in the future. For sending voice messages, use the * sendVoice method instead. * - * Objects defined as-is july 2016 + * Objects defined as-is January 2017 * * @see https://core.telegram.org/bots/api#sendaudio */ @@ -30,12 +30,14 @@ class SendAudio extends TelegramMethods public $chat_id = ''; /** - * Audio file to send. Associate an InputFile with it + * Audio file to send. Pass a file_id as String to send an audio file that exists on the Telegram servers + * (recommended), pass an HTTP URL as a String for Telegram to get an audio file from the Internet, or upload a new + * one using the InputFile class * - * @see unreal4u\TelegramAPI\Telegram\Types\Custom\InputFile - * @var InputFile + * @see InputFile + * @var string|InputFile */ - public $audio = null; + public $audio = ''; /** * Optional. Audio caption, 0-200 characters diff --git a/src/Telegram/Methods/SendChatAction.php b/src/Telegram/Methods/SendChatAction.php index 60b81a8..198e687 100644 --- a/src/Telegram/Methods/SendChatAction.php +++ b/src/Telegram/Methods/SendChatAction.php @@ -4,7 +4,11 @@ namespace unreal4u\TelegramAPI\Telegram\Methods; +use Psr\Log\LoggerInterface; use unreal4u\TelegramAPI\Abstracts\TelegramMethods; +use unreal4u\TelegramAPI\Abstracts\TelegramTypes; +use unreal4u\TelegramAPI\InternalFunctionality\TelegramRawData; +use unreal4u\TelegramAPI\Telegram\Types\Custom\ResultBoolean; /** * 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 @@ -42,4 +46,9 @@ public function getMandatoryFields(): array 'action', ]; } + + public static function bindToObject(TelegramRawData $data, LoggerInterface $logger): TelegramTypes + { + return new ResultBoolean($data->getResultBoolean(), $logger); + } } diff --git a/src/Telegram/Methods/SendContact.php b/src/Telegram/Methods/SendContact.php index dd685a5..744c766 100644 --- a/src/Telegram/Methods/SendContact.php +++ b/src/Telegram/Methods/SendContact.php @@ -4,6 +4,7 @@ namespace unreal4u\TelegramAPI\Telegram\Methods; +use unreal4u\TelegramAPI\Abstracts\KeyboardMethods; use unreal4u\TelegramAPI\Abstracts\TelegramMethods; /** @@ -56,9 +57,9 @@ class SendContact extends TelegramMethods /** * Optional. Additional interface options. A JSON-serialized object for a custom reply keyboard, instructions to * hide keyboard or to force a reply from the user. - * @var null + * @var KeyboardMethods */ - public $reply_markup = null; + public $reply_markup; public function getMandatoryFields(): array { diff --git a/src/Telegram/Methods/SendDocument.php b/src/Telegram/Methods/SendDocument.php index 4050ea7..c055208 100644 --- a/src/Telegram/Methods/SendDocument.php +++ b/src/Telegram/Methods/SendDocument.php @@ -4,6 +4,7 @@ namespace unreal4u\TelegramAPI\Telegram\Methods; +use unreal4u\TelegramAPI\Abstracts\KeyboardMethods; use unreal4u\TelegramAPI\Abstracts\TelegramMethods; use unreal4u\TelegramAPI\Telegram\Types\Custom\InputFile; @@ -11,7 +12,7 @@ * Use this method to send general files. On success, the sent Message is returned. Bots can currently send files of any * type of up to 50 MB in size, this limit may be changed in the future. * - * Objects defined as-is july 2016 + * Objects defined as-is January 2017 * * @see https://core.telegram.org/bots/api#senddocument */ @@ -24,14 +25,13 @@ class SendDocument extends TelegramMethods public $chat_id = ''; /** - * File to send. You can either pass a file_id as String to resend a file that is already on the Telegram servers, - * or upload a new file using the InputFile class + * File to send. Pass a file_id as String to send a file that exists on the Telegram servers (recommended), pass an + * HTTP URL as a String for Telegram to get a file from the Internet, or upload a new one using the InputFile class * - * @see unreal4u\TelegramAPI\Telegram\Types\Custom\InputFile - * - * @var InputFile + * @see InputFile + * @var string|InputFile */ - public $document = null; + public $document = ''; /** * Optional. Document caption (may also be used when resending documents by file_id), 0-200 characters @@ -56,9 +56,9 @@ class SendDocument extends TelegramMethods /** * Optional. Additional interface options. A JSON-serialized object for a custom reply keyboard, instructions to * hide keyboard or to force a reply from the user - * @var null + * @var KeyboardMethods */ - public $reply_markup = null; + public $reply_markup; public function getMandatoryFields(): array { diff --git a/src/Telegram/Methods/SendLocation.php b/src/Telegram/Methods/SendLocation.php index 6d4ce9b..5ae528f 100644 --- a/src/Telegram/Methods/SendLocation.php +++ b/src/Telegram/Methods/SendLocation.php @@ -4,6 +4,7 @@ namespace unreal4u\TelegramAPI\Telegram\Methods; +use unreal4u\TelegramAPI\Abstracts\KeyboardMethods; use unreal4u\TelegramAPI\Abstracts\TelegramMethods; /** @@ -50,9 +51,9 @@ class SendLocation extends TelegramMethods /** * Optional. Additional interface options. A JSON-serialized object for a custom reply keyboard, instructions to * hide keyboard or to force a reply from the user. - * @var null + * @var KeyboardMethods */ - public $reply_markup = null; + public $reply_markup; public function getMandatoryFields(): array { diff --git a/src/Telegram/Methods/SendMessage.php b/src/Telegram/Methods/SendMessage.php index 8dcc5d6..493bda7 100644 --- a/src/Telegram/Methods/SendMessage.php +++ b/src/Telegram/Methods/SendMessage.php @@ -60,7 +60,7 @@ class SendMessage extends TelegramMethods * hide keyboard or to force a reply from the user * @var KeyboardMethods */ - public $reply_markup = null; + public $reply_markup; public function getMandatoryFields(): array { diff --git a/src/Telegram/Methods/SendPhoto.php b/src/Telegram/Methods/SendPhoto.php index ed8c167..e6e5e4b 100644 --- a/src/Telegram/Methods/SendPhoto.php +++ b/src/Telegram/Methods/SendPhoto.php @@ -5,11 +5,12 @@ namespace unreal4u\TelegramAPI\Telegram\Methods; use unreal4u\TelegramAPI\Abstracts\TelegramMethods; +use unreal4u\TelegramAPI\Telegram\Types\Custom\InputFile; /** * Use this method to send photos. On success, the sent Message is returned * - * Objects defined as-is july 2016 + * Objects defined as-is January 2017 * * @see https://core.telegram.org/bots/api#sendphoto */ @@ -22,12 +23,13 @@ class SendPhoto extends TelegramMethods public $chat_id = ''; /** - * Photo to send. You can either pass a file_id as String to resend a photo that is already on the Telegram servers, - * or upload a new photo using the InputFile class - * @see unreal4u\TelegramAPI\Telegram\Types\Custom\InputFile - * @var string + * Photo to send. Pass a file_id as String to send a photo that exists on the Telegram servers (recommended), pass + * an HTTP URL as a String for Telegram to get a photo from the Internet, or upload a new photo using the InputFile + * class. + * @see InputFile + * @var string|InputFile */ - public $photo = null; + public $photo = ''; /** * Optional. Photo caption (may also be used when resending photos by file_id) @@ -54,7 +56,7 @@ class SendPhoto extends TelegramMethods * hide keyboard or to force a reply from the user * @var null */ - public $reply_markup = null; + public $reply_markup; public function getMandatoryFields(): array { diff --git a/src/Telegram/Methods/SendSticker.php b/src/Telegram/Methods/SendSticker.php index 715cdb8..15a2672 100644 --- a/src/Telegram/Methods/SendSticker.php +++ b/src/Telegram/Methods/SendSticker.php @@ -4,6 +4,7 @@ namespace unreal4u\TelegramAPI\Telegram\Methods; +use unreal4u\TelegramAPI\Abstracts\KeyboardMethods; use unreal4u\TelegramAPI\Abstracts\TelegramMethods; use unreal4u\TelegramAPI\Telegram\Types\Custom\InputFile; @@ -23,12 +24,13 @@ class SendSticker extends TelegramMethods public $chat_id = ''; /** - * Sticker to send. You can either pass a file_id as String to resend a sticker that is already on the Telegram - * servers, or upload a new sticker using the InputFile class - * @see unreal4u\TelegramAPI\Telegram\Types\Custom\InputFile. - * @var InputFile + * Sticker to send. Pass a file_id as String to send a file that exists on the Telegram servers (recommended), pass + * an HTTP URL as a String for Telegram to get a .webp file from the Internet, or upload a new one using the + * InputFile class + * @see InputFile + * @var string|InputFile */ - public $sticker = null; + public $sticker = ''; /** * Optional. Sends the message silently. iOS users will not receive a notification, Android users will receive a @@ -47,9 +49,9 @@ class SendSticker extends TelegramMethods /** * Optional. Additional interface options. A JSON-serialized object for a custom reply keyboard, instructions to * hide keyboard or to force a reply from the user - * @var null + * @var KeyboardMethods */ - public $reply_markup = null; + public $reply_markup; public function getMandatoryFields(): array { diff --git a/src/Telegram/Methods/SendVenue.php b/src/Telegram/Methods/SendVenue.php index 946c186..615a7e6 100644 --- a/src/Telegram/Methods/SendVenue.php +++ b/src/Telegram/Methods/SendVenue.php @@ -4,6 +4,7 @@ namespace unreal4u\TelegramAPI\Telegram\Methods; +use unreal4u\TelegramAPI\Abstracts\KeyboardMethods; use unreal4u\TelegramAPI\Abstracts\TelegramMethods; /** @@ -68,9 +69,9 @@ class SendVenue extends TelegramMethods /** * Optional. Additional interface options. A JSON-serialized object for a custom reply keyboard, instructions to * hide keyboard or to force a reply from the user. - * @var null + * @var KeyboardMethods */ - public $reply_markup = null; + public $reply_markup; public function getMandatoryFields(): array { diff --git a/src/Telegram/Methods/SendVideo.php b/src/Telegram/Methods/SendVideo.php index 2df9b97..a9c0b24 100644 --- a/src/Telegram/Methods/SendVideo.php +++ b/src/Telegram/Methods/SendVideo.php @@ -4,6 +4,7 @@ namespace unreal4u\TelegramAPI\Telegram\Methods; +use unreal4u\TelegramAPI\Abstracts\KeyboardMethods; use unreal4u\TelegramAPI\Abstracts\TelegramMethods; use unreal4u\TelegramAPI\Telegram\Types\Custom\InputFile; @@ -12,7 +13,7 @@ * success, the sent Message is returned. Bots can currently send video files of up to 50 MB in size, this limit may be * changed in the future. * - * Objects defined as-is july 2016 + * Objects defined as-is January 2017 * * @see https://core.telegram.org/bots/api#sendvideo */ @@ -25,12 +26,13 @@ class SendVideo extends TelegramMethods public $chat_id = ''; /** - * Video to send. You can either pass a file_id as String to resend a video that is already on the Telegram servers, - * or upload a new video file using the InputFile class - * @see unreal4u\TelegramAPI\Telegram\Types\Custom\InputFile - * @var InputFile + * Video to send. Pass a file_id as String to send a video that exists on the Telegram servers (recommended), pass + * an HTTP URL as a String for Telegram to get a video from the Internet, or upload a new video using the InputFile + * class + * @see InputFile + * @var string|InputFile */ - public $video = null; + public $video = ''; /** * Optional. Duration of sent video in seconds @@ -73,9 +75,9 @@ class SendVideo extends TelegramMethods /** * Optional. Additional interface options. A JSON-serialized object for a custom reply keyboard, instructions to * hide keyboard or to force a reply from the user - * @var null + * @var KeyboardMethods */ - public $reply_markup = null; + public $reply_markup; public function getMandatoryFields(): array { diff --git a/src/Telegram/Methods/SendVoice.php b/src/Telegram/Methods/SendVoice.php index c33669c..e5e2806 100644 --- a/src/Telegram/Methods/SendVoice.php +++ b/src/Telegram/Methods/SendVoice.php @@ -4,6 +4,7 @@ namespace unreal4u\TelegramAPI\Telegram\Methods; +use unreal4u\TelegramAPI\Abstracts\KeyboardMethods; use unreal4u\TelegramAPI\Abstracts\TelegramMethods; use unreal4u\TelegramAPI\Telegram\Types\Custom\InputFile; @@ -26,12 +27,13 @@ class SendVoice extends TelegramMethods public $chat_id = ''; /** - * Audio file to send. You can either pass a file_id as String to resend an audio that is already on the Telegram - * servers, or upload a new audio file using the InputFile class - * @see unreal4u\TelegramAPI\Telegram\Types\Custom\InputFile - * @var InputFile + * Audio file to send. Pass a file_id as String to send a file that exists on the Telegram servers (recommended), + * pass an HTTP URL as a String for Telegram to get a file from the Internet, or upload a new one using the + * InputFile class + * @see InputFile + * @var string|InputFile */ - public $voice = null; + public $voice = ''; /** * Optional. Audio caption, 0-200 characters @@ -40,7 +42,7 @@ class SendVoice extends TelegramMethods public $caption = ''; /** - * Optional. Duration of sent video in seconds + * Optional. Duration of sent voice message in seconds * @var int */ public $duration = 0; @@ -62,9 +64,9 @@ class SendVoice extends TelegramMethods /** * Optional. Additional interface options. A JSON-serialized object for a custom reply keyboard, instructions to * hide keyboard or to force a reply from the user - * @var null + * @var KeyboardMethods */ - public $reply_markup = null; + public $reply_markup; public function getMandatoryFields(): array { diff --git a/src/Telegram/Methods/SetWebhook.php b/src/Telegram/Methods/SetWebhook.php index fc8bc8b..fa2781f 100644 --- a/src/Telegram/Methods/SetWebhook.php +++ b/src/Telegram/Methods/SetWebhook.php @@ -8,6 +8,7 @@ use unreal4u\TelegramAPI\Abstracts\TelegramMethods; use unreal4u\TelegramAPI\Abstracts\TelegramTypes; use unreal4u\TelegramAPI\InternalFunctionality\TelegramRawData; +use unreal4u\TelegramAPI\Telegram\Types\Custom\InputFile; use unreal4u\TelegramAPI\Telegram\Types\Custom\ResultBoolean; /** @@ -26,7 +27,7 @@ *
  • Ports currently supported for Webhooks: 443, 80, 88, 8443.
    • * * - * Objects defined as-is December 2016 + * Objects defined as-is January 2017 * * @see https://core.telegram.org/bots/api#setwebhook */ @@ -41,9 +42,10 @@ class SetWebhook extends TelegramMethods /** * Optional. Upload your public key certificate so that the root certificate in use can be checked. See our * self-signed guide for details. - * @var string + * @see https://core.telegram.org/bots/self-signed + * @var InputFile */ - public $certificate = ''; + public $certificate; /** * Maximum allowed number of simultaneous HTTPS connections to the webhook for update delivery, 1-100. Defaults to @@ -74,6 +76,8 @@ public static function bindToObject(TelegramRawData $data, LoggerInterface $logg public function getMandatoryFields(): array { - return []; + return [ + 'url', + ]; } } diff --git a/src/Telegram/Types/Animation.php b/src/Telegram/Types/Animation.php index 5c7ad46..6024400 100644 --- a/src/Telegram/Types/Animation.php +++ b/src/Telegram/Types/Animation.php @@ -5,8 +5,6 @@ namespace unreal4u\TelegramAPI\Telegram\Types; use unreal4u\TelegramAPI\Abstracts\TelegramTypes; -use unreal4u\TelegramAPI\Telegram\Types\Custom\MessageEntityArray; -use unreal4u\TelegramAPI\Telegram\Types\Custom\PhotoSizeArray; /** * You can provide an animation for your game so that it looks stylish in chats (check out Lumberjack for an example). @@ -28,7 +26,7 @@ class Animation extends TelegramTypes * Optional. Animation thumbnail as defined by sender * @var PhotoSize */ - public $thumb = null; + public $thumb; /** * Optional. Original animation filename as defined by sender diff --git a/src/Telegram/Types/CallbackQuery.php b/src/Telegram/Types/CallbackQuery.php index 1a304a1..9fe76af 100644 --- a/src/Telegram/Types/CallbackQuery.php +++ b/src/Telegram/Types/CallbackQuery.php @@ -11,7 +11,11 @@ * originated the query was attached to a message sent by the bot, the field message will be presented. If the button * was attached to a message sent via the bot (in inline mode), the field inline_message_id will be presented. * - * Objects defined as-is november 2016 + * NOTE: After the user presses an inline button, Telegram clients will display a progress bar until you call + * answerCallbackQuery. It is, therefore, necessary to react by calling answerCallbackQuery even if no notification to + * the user is needed (e.g., without specifying any of the optional parameters). + * + * Objects defined as-is January 2017 * * @see https://core.telegram.org/bots/api#callbackquery */ @@ -27,14 +31,14 @@ class CallbackQuery extends TelegramTypes * The user that chose the result * @var User */ - public $from = null; + public $from; /** * Optional. Message with the callback button that originated the query. Note that message content and message date * will not be available if the message is too old * @var Message */ - public $message = null; + public $message; /** * Optional. Identifier of the message sent via the bot in inline mode, that originated the query diff --git a/src/Telegram/Types/ChatMember.php b/src/Telegram/Types/ChatMember.php index 0611dc5..e3f9e6d 100644 --- a/src/Telegram/Types/ChatMember.php +++ b/src/Telegram/Types/ChatMember.php @@ -19,7 +19,7 @@ class ChatMember extends TelegramTypes * Information about the user * @var User */ - public $user = null; + public $user; /** * The member's status in the chat. Can be “creator”, “administrator”, “member”, “left” or diff --git a/src/Telegram/Types/Custom/InlineKeyboardButtonArray.php b/src/Telegram/Types/Custom/InlineKeyboardButtonArray.php index b825dd3..7faa8b0 100644 --- a/src/Telegram/Types/Custom/InlineKeyboardButtonArray.php +++ b/src/Telegram/Types/Custom/InlineKeyboardButtonArray.php @@ -11,8 +11,6 @@ /** * Mockup class to generate a real telegram update representation - * - * @TODO Test this, it may not work as expected! */ class InlineKeyboardButtonArray extends CustomType implements CustomArrayType { @@ -21,8 +19,8 @@ class InlineKeyboardButtonArray extends CustomType implements CustomArrayType public function __construct(array $data = null, LoggerInterface $logger = null) { if (!empty($data)) { - foreach ($data as $id => $photo) { - $this->data[$id] = new Button(); + foreach ($data as $rowId => $button) { + $this->data[$rowId][] = new Button($data, $logger); } } } diff --git a/src/Telegram/Types/Custom/KeyboardButtonArray.php b/src/Telegram/Types/Custom/KeyboardButtonArray.php index 07e84d6..ae79a30 100644 --- a/src/Telegram/Types/Custom/KeyboardButtonArray.php +++ b/src/Telegram/Types/Custom/KeyboardButtonArray.php @@ -11,8 +11,6 @@ /** * Mockup class to generate a real telegram update representation - * - * @TODO Test this, it may not work as expected! */ class KeyboardButtonArray extends CustomType implements CustomArrayType { @@ -21,8 +19,8 @@ class KeyboardButtonArray extends CustomType implements CustomArrayType public function __construct(array $data = null, LoggerInterface $logger = null) { if (!empty($data)) { - foreach ($data as $id => $photo) { - $this->data[$id] = new KeyboardButton(); + foreach ($data as $rowId => $button) { + $this->data[$rowId][] = new KeyboardButton($data, $logger); } } } diff --git a/src/Telegram/Types/Document.php b/src/Telegram/Types/Document.php index f01a929..8515353 100644 --- a/src/Telegram/Types/Document.php +++ b/src/Telegram/Types/Document.php @@ -25,7 +25,7 @@ class Document extends TelegramTypes * Optional. Document thumbnail as defined by sender * @var PhotoSize */ - public $thumb = null; + public $thumb; /** * Optional. Original filename as defined by sender diff --git a/src/Telegram/Types/Inline/ChosenResult.php b/src/Telegram/Types/Inline/ChosenResult.php index f06e48d..f3f085f 100644 --- a/src/Telegram/Types/Inline/ChosenResult.php +++ b/src/Telegram/Types/Inline/ChosenResult.php @@ -11,7 +11,7 @@ /** * This object represents a result of an inline query that was chosen by the user and sent to their chat partner. * - * Objects defined as-is july 2016 + * Objects defined as-is January 2017 * * @see https://core.telegram.org/bots/api#choseninlineresult */ @@ -27,13 +27,13 @@ class ChosenResult extends TelegramTypes * The user that chose the result * @var User */ - public $from = null; + public $from; /** * Optional. Sender location, only for bots that require user location * @var Location */ - public $location = null; + public $location; /** * Optional. Identifier of the sent inline message. Available only if there is an inline keyboard attached to the @@ -43,7 +43,7 @@ class ChosenResult extends TelegramTypes public $inline_message_id = ''; /** - * Text of the query + * The query that was used to obtain the result * @var string */ public $query = ''; diff --git a/src/Telegram/Types/Inline/Keyboard/Markup.php b/src/Telegram/Types/Inline/Keyboard/Markup.php index 7369395..5e35038 100644 --- a/src/Telegram/Types/Inline/Keyboard/Markup.php +++ b/src/Telegram/Types/Inline/Keyboard/Markup.php @@ -24,7 +24,7 @@ class Markup extends TelegramTypes { /** * Array of button rows, each represented by an Array of InlineKeyboardButton objects - * @var array + * @var Button[] */ public $inline_keyboard = []; diff --git a/src/Telegram/Types/Inline/Query.php b/src/Telegram/Types/Inline/Query.php index 13eb935..08f4204 100644 --- a/src/Telegram/Types/Inline/Query.php +++ b/src/Telegram/Types/Inline/Query.php @@ -12,7 +12,7 @@ * This object represents an incoming inline query. When the user sends an empty query, your bot could return some * default or trending results. * - * Objects defined as-is january 2016 + * Objects defined as-is January 2017 * * @see https://core.telegram.org/bots/api#inlinequery */ @@ -28,16 +28,16 @@ class Query extends TelegramTypes * User‘s or bot’s first name * @var User */ - public $from = null; + public $from; /** * Optional. Sender location, only for bots that request user location * @var Location */ - public $location = null; + public $location; /** - * Text of the query + * Text of the query (up to 512 characters) * @var string */ public $query = ''; diff --git a/src/Telegram/Types/Inline/Query/Result.php b/src/Telegram/Types/Inline/Query/Result.php index a00cf99..02ed350 100644 --- a/src/Telegram/Types/Inline/Query/Result.php +++ b/src/Telegram/Types/Inline/Query/Result.php @@ -9,7 +9,7 @@ use unreal4u\TelegramAPI\Telegram\Types\Inline\Keyboard\Markup; /** - * This object represents one result of an inline query. Telegram clients currently support results of the following + * This object represents one result of an inline query. Telegram clients currently support results of the following 20 * types: * * InlineQueryResultCachedAudio @@ -23,6 +23,7 @@ * InlineQueryResultArticle * InlineQueryResultAudio * InlineQueryResultContact + * InlineQueryResultGame * InlineQueryResultDocument * InlineQueryResultGif * InlineQueryResultLocation @@ -32,7 +33,7 @@ * InlineQueryResultVideo * InlineQueryResultVoice * - * Objects defined as-is april 2016 + * Objects defined as-is January 2017 * * @see https://core.telegram.org/bots/api#inlinequeryresult */ diff --git a/src/Telegram/Types/Inline/Query/Result/Cached/Sticker.php b/src/Telegram/Types/Inline/Query/Result/Cached/Sticker.php index cd34258..a1c8037 100644 --- a/src/Telegram/Types/Inline/Query/Result/Cached/Sticker.php +++ b/src/Telegram/Types/Inline/Query/Result/Cached/Sticker.php @@ -24,7 +24,7 @@ class Sticker extends Result public $type = 'sticker'; /** - * A valid file identifier for the audio file + * A valid file identifier for the sticker * @var string */ public $sticker_file_id = ''; diff --git a/src/Telegram/Types/KeyboardButton.php b/src/Telegram/Types/KeyboardButton.php index 5354954..7da5525 100644 --- a/src/Telegram/Types/KeyboardButton.php +++ b/src/Telegram/Types/KeyboardButton.php @@ -4,6 +4,8 @@ namespace unreal4u\TelegramAPI\Telegram\Types; +use unreal4u\TelegramAPI\Abstracts\TelegramTypes; + /** * 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 are mutually exclusive. @@ -15,7 +17,7 @@ * * @see https://core.telegram.org/bots/api#keyboardbutton */ -class KeyboardButton +class KeyboardButton extends TelegramTypes { /** * Text of the button. If none of the optional fields are used, it will be sent to the bot as a message when the diff --git a/src/Telegram/Types/Message.php b/src/Telegram/Types/Message.php index 3f646b1..d046d78 100644 --- a/src/Telegram/Types/Message.php +++ b/src/Telegram/Types/Message.php @@ -27,7 +27,7 @@ class Message extends TelegramTypes * Optional. Sender, can be empty for messages sent to channels * @var User */ - public $from = null; + public $from; /** * Date the message was sent in Unix time @@ -39,19 +39,19 @@ class Message extends TelegramTypes * Conversation the message belongs to * @var Chat */ - public $chat = null; + public $chat; /** * Optional. For forwarded messages, sender of the original message * @var User */ - public $forward_from = null; + public $forward_from; /** * Optional. For messages forwarded from a channel, information about the original channel * @var Chat */ - public $forward_from_chat = null; + public $forward_from_chat; /** * Optional. For forwarded channel posts, identifier of the original message in the channel @@ -70,7 +70,7 @@ class Message extends TelegramTypes * reply_to_message fields even if it itself is a reply. * @var Message */ - public $reply_to_message = null; + public $reply_to_message; /** * Optional. Date the message was last edited in Unix time @@ -94,20 +94,20 @@ class Message extends TelegramTypes * Optional. Message is an audio file, information about the file * @var Audio */ - public $audio = null; + public $audio; /** * Optional. Message is a general file, information about the file * @var Document */ - public $document = null; + public $document; /** * Optional. Message is a game, information about the game * @see https://core.telegram.org/bots/api#games - * @var null + * @var Game */ - public $game = null; + public $game; /** * Optional. Message is a photo, available sizes of the photo @@ -119,19 +119,19 @@ class Message extends TelegramTypes * Optional. Message is a sticker, information about the sticker * @var Sticker */ - public $sticker = null; + public $sticker; /** * Optional. Message is a video, information about the video * @var Video */ - public $video = null; + public $video; /** * Optional. Message is a voice message, information about the file * @var Voice */ - public $voice = null; + public $voice; /** * Optional. Caption for the photo or video @@ -143,31 +143,31 @@ class Message extends TelegramTypes * Optional. Message is a shared contact, information about the contact * @var Contact */ - public $contact = null; + public $contact; /** * Optional. Message is a shared location, information about the location * @var Location */ - public $location = null; + public $location; /** * Optional. Message is a venue, information about the venue * @var Venue */ - public $venue = null; + public $venue; /** * Optional. A new member was added to the group, information about them (this member may be the bot itself) * @var User */ - public $new_chat_member = null; + public $new_chat_member; /** * Optional. A member was removed from the group, information about them (this member may be the bot itself) * @var User */ - public $left_chat_member = null; + public $left_chat_member; /** * Optional. A chat title was changed to this value @@ -230,7 +230,7 @@ class Message extends TelegramTypes * reply_to_message fields even if it is itself a reply. * @var Message */ - public $pinned_message = null; + public $pinned_message; /** * A message may contain one or more subobjects, map them always in this function diff --git a/src/Telegram/Types/MessageEntity.php b/src/Telegram/Types/MessageEntity.php index 3d58551..53ce909 100644 --- a/src/Telegram/Types/MessageEntity.php +++ b/src/Telegram/Types/MessageEntity.php @@ -45,7 +45,7 @@ class MessageEntity extends TelegramTypes * Optional. For “text_mention” only, the mentioned user * @var User */ - public $user = null; + public $user; protected function mapSubObjects(string $key, array $data): TelegramTypes { diff --git a/src/Telegram/Types/ReplyKeyboardMarkup.php b/src/Telegram/Types/ReplyKeyboardMarkup.php index 8a96f04..67d95c0 100644 --- a/src/Telegram/Types/ReplyKeyboardMarkup.php +++ b/src/Telegram/Types/ReplyKeyboardMarkup.php @@ -20,7 +20,7 @@ class ReplyKeyboardMarkup extends KeyboardMethods { /** * Array of button rows, each represented by an Array of KeyboardButton objects - * @var array + * @var KeyboardButton[] */ public $keyboard = []; diff --git a/src/Telegram/Types/Sticker.php b/src/Telegram/Types/Sticker.php index ac0d1a3..ec12d0e 100644 --- a/src/Telegram/Types/Sticker.php +++ b/src/Telegram/Types/Sticker.php @@ -5,7 +5,6 @@ namespace unreal4u\TelegramAPI\Telegram\Types; use unreal4u\TelegramAPI\Abstracts\TelegramTypes; -use unreal4u\TelegramAPI\Telegram\Types\Inline\Query\Result\Cached\Photo; /** * This object represents a sticker @@ -38,7 +37,7 @@ class Sticker extends TelegramTypes * Optional. Sticker thumbnail in .webp or .jpg format * @var PhotoSize */ - public $thumb = null; + public $thumb; /** * Optional. Emoji associated with the sticker diff --git a/src/Telegram/Types/Update.php b/src/Telegram/Types/Update.php index d7488b5..c2cf464 100644 --- a/src/Telegram/Types/Update.php +++ b/src/Telegram/Types/Update.php @@ -12,7 +12,7 @@ * This object represents an incoming update. * At most one of the optional parameters can be present in any given update. * - * Objects defined as-is november 2016 + * Objects defined as-is January 2017 * * @see https://core.telegram.org/bots/api#update */ @@ -30,43 +30,43 @@ class Update extends TelegramTypes * Optional. New incoming message of any kind — text, photo, sticker, etc. * @var Message */ - public $message = null; + public $message; /** * Optional. New version of a message that is known to the bot and was edited * @var Message */ - public $edited_message = null; + public $edited_message; /** * Optional. New incoming channel post of any kind — text, photo, sticker, etc. * @var Message */ - public $channel_post = null; + public $channel_post; /** * Optional. New version of a channel post that is known to the bot and was edited * @var Message */ - public $edited_channel_post = null; + public $edited_channel_post; /** * Optional. New incoming inline query * @var Query */ - public $inline_query = null; + public $inline_query; /** * Optional. The result of a inline query that was chosen by a user and sent to their chat partner * @var ChosenResult */ - public $chosen_inline_result = null; + public $chosen_inline_result; /** * Optional. New incoming callback query * @var CallbackQuery */ - public $callback_query = null; + public $callback_query; protected function mapSubObjects(string $key, array $data): TelegramTypes { diff --git a/src/Telegram/Types/UserProfilePhotos.php b/src/Telegram/Types/UserProfilePhotos.php index 717f777..d18eaa7 100644 --- a/src/Telegram/Types/UserProfilePhotos.php +++ b/src/Telegram/Types/UserProfilePhotos.php @@ -26,7 +26,7 @@ class UserProfilePhotos extends TelegramTypes * Requested profile pictures (in up to 4 sizes each) * NOTE: Is an array of an array of PhotoSize objects * - * @var array + * @var UserProfilePhotosArray[] */ public $photos = []; diff --git a/src/Telegram/Types/Venue.php b/src/Telegram/Types/Venue.php index ead281f..d2babfc 100644 --- a/src/Telegram/Types/Venue.php +++ b/src/Telegram/Types/Venue.php @@ -19,7 +19,7 @@ class Venue extends TelegramTypes * Venue location * @var Location */ - public $location = null; + public $location; /** * Name of the venue diff --git a/src/Telegram/Types/Video.php b/src/Telegram/Types/Video.php index c498116..05ccd00 100644 --- a/src/Telegram/Types/Video.php +++ b/src/Telegram/Types/Video.php @@ -5,7 +5,6 @@ namespace unreal4u\TelegramAPI\Telegram\Types; use unreal4u\TelegramAPI\Abstracts\TelegramTypes; -use unreal4u\TelegramAPI\Telegram\Types\Custom\PhotoSizeArray; /** * This object represents a video file @@ -44,7 +43,7 @@ class Video extends TelegramTypes * Optional. Video thumbnail * @var PhotoSize */ - public $thumb = null; + public $thumb; /** * Optional. Mime type of a file as defined by sender @@ -62,7 +61,7 @@ protected function mapSubObjects(string $key, array $data): TelegramTypes { switch ($key) { case 'thumb': - return new PhotoSizeArray($data, $this->logger); + return new PhotoSize($data, $this->logger); } return parent::mapSubObjects($key, $data); diff --git a/src/Telegram/Types/WebhookInfo.php b/src/Telegram/Types/WebhookInfo.php index 4d59b45..cd43563 100644 --- a/src/Telegram/Types/WebhookInfo.php +++ b/src/Telegram/Types/WebhookInfo.php @@ -45,4 +45,16 @@ class WebhookInfo extends TelegramTypes * @var int */ public $last_error_message = ''; + + /** + * Optional. Maximum allowed number of simultaneous HTTPS connections to the webhook for update delivery + * @var int + */ + public $max_connections; + + /** + * Optional. A list of update types the bot is subscribed to. Defaults to all update types + * @var string[] + */ + public $allowed_updates = []; } diff --git a/src/TgLog.php b/src/TgLog.php index 78bfd08..d2f29df 100644 --- a/src/TgLog.php +++ b/src/TgLog.php @@ -70,13 +70,13 @@ public function __construct(string $botToken, LoggerInterface $logger = null, Cl $this->botToken = $botToken; // Initialize new dummy logger (PSR-3 compatible) if not injected - if (is_null($logger)) { + if ($logger === null) { $logger = new DummyLogger(); } $this->logger = $logger; // Initialize new Guzzle client if not injected - if (is_null($client)) { + if ($client === null) { $client = new Client(); } $this->httpClient = $client; diff --git a/tests/Telegram/Methods/SetWebhookTest.php b/tests/Telegram/Methods/SetWebhookTest.php index 56e7e24..568fcb4 100644 --- a/tests/Telegram/Methods/SetWebhookTest.php +++ b/tests/Telegram/Methods/SetWebhookTest.php @@ -33,9 +33,20 @@ protected function tearDown() parent::tearDown(); } + /** + * @expectedException \unreal4u\TelegramAPI\Exceptions\MissingMandatoryField + * @expectedExceptionMessage url + */ + public function testMandatoryFields() + { + $setWebhook = new SetWebhook(); + $this->tgLog->performApiRequest($setWebhook); + } + public function testSetWebhook() { $setWebhook = new SetWebhook(); + $setWebhook->url = 'https://example.com/'; /** @var ResultBoolean $result */ $result = $this->tgLog->performApiRequest($setWebhook);