Merge branch 'develop' of https://github.com/php-telegram-bot/core into bot_api_3.0

Add some extra minor improvements.

CHANGELOG.md

@@ -5,7 +5,11 @@ Exclamation symbols (:exclamation:) note something of importance e.g. breaking c
 
 ## [Unreleased]
 ### Added
+- Callbacks can be added to be executed when callback queries are called.
+- New Bot API 3.1 changes (#550).
+- New entities, methods, update types and inline keyboard button for Payments (Bot API 3.0).
 ### Changed
+- [:exclamation:][unreleased-bc-request-class-refactor] Big refactor of the `Request` class, removing most custom method implementations.
 ### Deprecated
 ### Removed
 ### Fixed
@@ -17,7 +21,6 @@ Exclamation symbols (:exclamation:) note something of importance e.g. breaking c
 - Documents can be sent by providing its contents via Psr7 stream (as opposed to passing a file path).
 - Allow setting a custom Guzzle HTTP Client for requests (#511).
 - First implementations towards Bots API 3.0.
-- New entities, methods, update types and inline keyboard button for Payments.
 ### Changed
 - [:exclamation:][0.45.0-bc-chats-params-array] `Request::sendToActiveChats` and `DB::selectChats` now accept parameters as an options array and allow selecting of channels.
 ### Deprecated
@@ -122,6 +125,7 @@ Exclamation symbols (:exclamation:) note something of importance e.g. breaking c
 ### Deprecated
 - Move `hideKeyboard` to `removeKeyboard`.
 
+[unreleased-bc-request-class-refactor]: https://github.com/php-telegram-bot/core/wiki/Breaking-backwards-compatibility#request-class-refactor
 [0.45.0-bc-remove-deprecated-methods]: https://github.com/php-telegram-bot/core/wiki/Breaking-backwards-compatibility#remove-deprecated-methods
 [0.45.0-bc-chats-params-array]: https://github.com/php-telegram-bot/core/wiki/Breaking-backwards-compatibility#chats-params-array
 [0.45.0-bc-up-download-directory]: https://github.com/php-telegram-bot/core/wiki/Breaking-backwards-compatibility#up-download-directory

src/Commands/Command.php

@@ -11,10 +11,27 @@
 namespace Longman\TelegramBot\Commands;
 
 use Longman\TelegramBot\DB;
+use Longman\TelegramBot\Entities\CallbackQuery;
+use Longman\TelegramBot\Entities\ChosenInlineResult;
+use Longman\TelegramBot\Entities\InlineQuery;
+use Longman\TelegramBot\Entities\Message;
+use Longman\TelegramBot\Entities\Update;
 use Longman\TelegramBot\Request;
 use Longman\TelegramBot\Telegram;
-use Longman\TelegramBot\Entities\Update;
 
+/**
+ * Class Command
+ *
+ * Base class for commands. It includes some helper methods that can fetch data directly from the Update object.
+ *
+ * @method Message             getMessage()            Optional. New incoming message of any kind — text, photo, sticker, etc.
+ * @method Message             getEditedMessage()      Optional. New version of a message that is known to the bot and was edited
+ * @method Message             getChannelPost()        Optional. New post in the channel, can be any kind — text, photo, sticker, etc.
+ * @method Message             getEditedChannelPost()  Optional. New version of a post in the channel that is known to the bot and was edited
+ * @method InlineQuery         getInlineQuery()        Optional. New incoming inline query
+ * @method ChosenInlineResult  getChosenInlineResult() Optional. The result of an inline query that was chosen by a user and sent to their chat partner.
+ * @method CallbackQuery       getCallbackQuery()      Optional. New incoming callback query
+ */
 abstract class Command
 {
     /**
@@ -31,13 +48,6 @@ abstract class Command
      */
     protected $update;
 
-    /**
-     * Message object
-     *
-     * @var \Longman\TelegramBot\Entities\Message
-     */
-    protected $message;
-
     /**
      * Name
      *
@@ -117,8 +127,7 @@ abstract class Command
     public function setUpdate(Update $update = null)
     {
         if ($update !== null) {
-            $this->update  = $update;
-            $this->message = $this->update->getMessage();
+            $this->update = $update;
         }
 
         return $this;
@@ -178,13 +187,21 @@ abstract class Command
     }
 
     /**
-     * Get message object
+     * Relay any non-existing function calls to Update object.
      *
-     * @return \Longman\TelegramBot\Entities\Message
+     * This is purely a helper method to make requests from within execute() method easier.
+     *
+     * @param string $name
+     * @param array  $arguments
+     *
+     * @return Command
      */
-    public function getMessage()
+    public function __call($name, array $arguments)
     {
-        return $this->message;
+        if ($this->update === null) {
+            return null;
+        }
+        return call_user_func_array([$this->update, $name], $arguments);
     }
 
     /**

src/Commands/SystemCommands/CallbackqueryCommand.php

@@ -18,6 +18,11 @@ use Longman\TelegramBot\Request;
  */
 class CallbackqueryCommand extends SystemCommand
 {
+    /**
+     * @var callable[]
+     */
+    protected static $callbacks = [];
+
     /**
      * @var string
      */
@@ -46,6 +51,21 @@ class CallbackqueryCommand extends SystemCommand
         //$query_id       = $callback_query->getId();
         //$query_data     = $callback_query->getData();
 
+        // Call all registered callbacks.
+        foreach (self::$callbacks as $callback) {
+            $callback($this->getUpdate()->getCallbackQuery());
+        }
+
         return Request::answerCallbackQuery(['callback_query_id' => $this->getUpdate()->getCallbackQuery()->getId()]);
     }
+
+    /**
+     * Add a new callback handler for callback queries.
+     *
+     * @param $callback
+     */
+    public static function addCallbackHandler($callback)
+    {
+        self::$callbacks[] = $callback;
+    }
 }

src/Entities/Chat.php

@@ -15,23 +15,39 @@ namespace Longman\TelegramBot\Entities;
  *
  * @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.
- * @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.
+ * @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.
+ * @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.
  */
 class Chat extends Entity
 {
+    /**
+     * {@inheritdoc}
+     */
+    public function subEntities()
+    {
+        return [
+            'photo' => ChatPhoto::class,
+        ];
+    }
+
     public function __construct($data)
     {
         parent::__construct($data);

src/Entities/ChatMember.php

@@ -15,8 +15,22 @@ namespace Longman\TelegramBot\Entities;
  *
  * @link https://core.telegram.org/bots/api#chatmember
  *
- * @method User   getUser()   Information about the user.
- * @method string getStatus() The member's status in the chat. Can be "creator", "administrator", "member", "left" or "kicked"
+ * @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 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   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   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
  */
 class ChatMember extends Entity
 {

src/Entities/ChatPhoto.php

+<?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 ChatPhoto
+ *
+ * @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.
+ */
+class ChatPhoto extends Entity
+{
+
+}

src/Entities/Payments/PreCheckoutQuery.php

@@ -36,7 +36,7 @@ class PreCheckoutQuery extends Entity
     public function subEntities()
     {
         return [
-            'user' => User::class,
+            'user'       => User::class,
             'order_info' => OrderInfo::class,
         ];
     }

src/Entities/Payments/ShippingQuery.php

@@ -33,7 +33,7 @@ class ShippingQuery extends Entity
     public function subEntities()
     {
         return [
-            'user' => User::class,
+            'user'             => User::class,
             'shipping_address' => ShippingAddress::class,
         ];
     }

src/Telegram.php

@@ -787,7 +787,19 @@ class Telegram
             throw new TelegramException('Hook url is empty!');
         }
 
-        $result = Request::setWebhook($url, $data);
+        $data        = array_intersect_key($data, array_flip([
+            'certificate',
+            'max_connections',
+            'allowed_updates',
+        ]));
+        $data['url'] = $url;
+
+        // If the certificate is passed as a path, encode and add the file to the data array.
+        if (!empty($data['certificate']) && is_string($data['certificate'])) {
+            $data['certificate'] = Request::encodeFile($data['certificate']);
+        }
+
+        $result = Request::setWebhook($data);
 
         if (!$result->isOk()) {
             throw new TelegramException(

tests/unit/Commands/CommandTest.php

@@ -163,9 +163,7 @@ class CommandTest extends TestCase
         $update  = TestHelpers::getFakeUpdateObject();
         $message = $update->getMessage();
         $stub->setUpdate($update);
-        $this->assertAttributeEquals($update, 'update', $stub);
         $this->assertEquals($update, $stub->getUpdate());
-        $this->assertAttributeEquals($message, 'message', $stub);
         $this->assertEquals($message, $stub->getMessage());
     }