Implement Telegram Games platform.

Author: noplanman

CHANGELOG.md

@@ -5,6 +5,7 @@ Exclamation symbols (:exclamation:) note something of importance e.g. breaking c
 
 ## [Unreleased]
 ### Added
+- Telegram Games platform!
 ### Changed
 ### Deprecated
 ### Removed

src/DB.php

@@ -831,15 +831,15 @@ public static function insertMessageRequest(Message $message)
                 (
                     `id`, `user_id`, `chat_id`, `date`, `forward_from`, `forward_from_chat`, `forward_from_message_id`,
                     `forward_date`, `reply_to_chat`, `reply_to_message`, `media_group_id`, `text`, `entities`, `audio`, `document`,
-                    `photo`, `sticker`, `video`, `voice`, `video_note`, `caption`, `contact`,
+                    `game`, `photo`, `sticker`, `video`, `voice`, `video_note`, `caption`, `contact`,
                     `location`, `venue`, `new_chat_members`, `left_chat_member`,
                     `new_chat_title`,`new_chat_photo`, `delete_chat_photo`, `group_chat_created`,
                     `supergroup_chat_created`, `channel_chat_created`,
                     `migrate_from_chat_id`, `migrate_to_chat_id`, `pinned_message`
                 ) VALUES (
                     :message_id, :user_id, :chat_id, :date, :forward_from, :forward_from_chat, :forward_from_message_id,
                     :forward_date, :reply_to_chat, :reply_to_message, :media_group_id, :text, :entities, :audio, :document,
-                    :photo, :sticker, :video, :voice, :video_note, :caption, :contact,
+                    :game, :photo, :sticker, :video, :voice, :video_note, :caption, :contact,
                     :location, :venue, :new_chat_members, :left_chat_member,
                     :new_chat_title, :new_chat_photo, :delete_chat_photo, :group_chat_created,
                     :supergroup_chat_created, :channel_chat_created,
@@ -883,6 +883,7 @@ public static function insertMessageRequest(Message $message)
             $sth->bindValue(':entities', $t = self::entitiesArrayToJson($message->getEntities(), null));
             $sth->bindValue(':audio', $message->getAudio());
             $sth->bindValue(':document', $message->getDocument());
+            $sth->bindValue(':game', $message->getGame());
             $sth->bindValue(':photo', $t = self::entitiesArrayToJson($message->getPhoto(), null));
             $sth->bindValue(':sticker', $message->getSticker());
             $sth->bindValue(':video', $message->getVideo());

src/Entities/CallbackQuery.php

@@ -22,6 +22,7 @@
  * @method Message getMessage()         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
  * @method string  getInlineMessageId() Optional. Identifier of the message sent via the bot in inline mode, that originated the query
  * @method string  getData()            Data associated with the callback button. Be aware that a bad client can send arbitrary data in this field
+ * @method string  getGameShortName()   Optional. Short name of a Game to be returned, serves as the unique identifier for the game
  */
 class CallbackQuery extends Entity
 {

src/Entities/Games/Animation.php

@@ -0,0 +1,31 @@
+<?php
+/**
+ * This file is part of the TelegramBot package.
+ *
+ * (c) Avtandil Kikabidze aka LONGMAN <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Longman\TelegramBot\Entities\Games;
+
+use Longman\TelegramBot\Entities\Entity;
+
+/**
+ * Class Animation
+ *
+ * You can provide an animation for your game so that it looks stylish in chats (check out Lumberjack for an example). This object represents an animation file to be displayed in the message containing a game.
+ *
+ * @link https://core.telegram.org/bots/api#animation
+ *
+ * @method string    getFileId()   Unique file identifier
+ * @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
+{
+
+}

src/Entities/Games/CallbackGame.php

@@ -0,0 +1,25 @@
+<?php
+/**
+ * This file is part of the TelegramBot package.
+ *
+ * (c) Avtandil Kikabidze aka LONGMAN <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Longman\TelegramBot\Entities\Games;
+
+use Longman\TelegramBot\Entities\Entity;
+
+/**
+ * Class CallbackGame
+ *
+ * A placeholder, currently holds no information. Use BotFather to set up your game.
+ *
+ * @link https://core.telegram.org/bots/api#callbackgame
+ **/
+class CallbackGame extends Entity
+{
+
+}

src/Entities/Games/Game.php

@@ -0,0 +1,71 @@
+<?php
+/**
+ * This file is part of the TelegramBot package.
+ *
+ * (c) Avtandil Kikabidze aka LONGMAN <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Longman\TelegramBot\Entities\Games;
+
+use Longman\TelegramBot\Entities\Entity;
+use Longman\TelegramBot\Entities\MessageEntity;
+
+/**
+ * Class Game
+ *
+ * This object represents a game. Use BotFather to create and edit games, their short names will act as unique identifiers.
+ *
+ * @link https://core.telegram.org/bots/api#game
+ *
+ * @method string    getTitle()        Title of the game
+ * @method string    getDescription()  Description of the game
+ * @method string    getText()         Optional. Brief description of the game or high scores included in the game message. Can be automatically edited to include current high scores for the game when the bot calls setGameScore, or manually edited using editMessageText. 0-4096 characters.
+ * @method Animation getAnimation()    Optional. Animation that will be displayed in the game message in chats. Upload via BotFather
+ **/
+class Game extends Entity
+{
+    /**
+     * {@inheritdoc}
+     */
+    protected function subEntities()
+    {
+        return [
+            'photo'         => PhotoSize::class,
+            'text_entities' => MessageEntity::class,
+            'animation'     => Animation::class,
+        ];
+    }
+
+    /**
+     * Photo that will be displayed in the game message in chats.
+     *
+     * This method overrides the default getPhoto method
+     * and returns a nice array of PhotoSize objects.
+     *
+     * @return null|PhotoSize[]
+     */
+    public function getPhoto()
+    {
+        $pretty_array = $this->makePrettyObjectArray(PhotoSize::class, 'photo');
+
+        return empty($pretty_array) ? null : $pretty_array;
+    }
+
+    /**
+     * Optional. Special entities that appear in text, such as usernames, URLs, bot commands, etc.
+     *
+     * This method overrides the default getTextEntities method
+     * and returns a nice array of MessageEntity objects.
+     *
+     * @return null|MessageEntity[]
+     */
+    public function getTextEntities()
+    {
+        $pretty_array = $this->makePrettyObjectArray(MessageEntity::class, 'text_entities');
+
+        return empty($pretty_array) ? null : $pretty_array;
+    }
+}

src/Entities/Games/GameHighScore.php

@@ -0,0 +1,37 @@
+<?php
+/**
+ * This file is part of the TelegramBot package.
+ *
+ * (c) Avtandil Kikabidze aka LONGMAN <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Longman\TelegramBot\Entities\Games;
+
+use Longman\TelegramBot\Entities\Entity;
+
+/**
+ * Class GameHighScore
+ *
+ * This object represents one row of the high scores table for a game.
+ *
+ * @link https://core.telegram.org/bots/api#gamehighscore
+ *
+ * @method int  getPosition() Position in high score table for the game
+ * @method User getUser()     User
+ * @method int  getScore()    Score
+ **/
+class GameHighScore extends Entity
+{
+    /**
+     * {@inheritdoc}
+     */
+    protected function subEntities()
+    {
+        return [
+            'user' => User::class,
+        ];
+    }
+}

src/Entities/InlineKeyboardButton.php

@@ -17,18 +17,20 @@
  *
  * @link https://core.telegram.org/bots/api#inlinekeyboardbutton
  *
- * @method string getText()                         Label text on the button
- * @method string getUrl()                          Optional. HTTP url to be opened when button is pressed
- * @method string getCallbackData()                 Optional. Data to be sent in a callback query to the bot when button is pressed, 1-64 bytes
- * @method string getSwitchInlineQuery()            Optional. If set, pressing the button will prompt the user to select one of their chats, open that chat and insert the bot's username and the specified inline query in the input field. Can be empty, in which case just the bot’s username will be inserted.
- * @method string getSwitchInlineQueryCurrentChat() Optional. If set, pressing the button will insert the bot‘s username and the specified inline query in the current chat's input field. Can be empty, in which case only the bot’s username will be inserted.
- * @method bool   getPay()                          Optional. Specify True, to send a Pay button.
+ * @method string       getText()                         Label text on the button
+ * @method string       getUrl()                          Optional. HTTP url to be opened when button is pressed
+ * @method string       getCallbackData()                 Optional. Data to be sent in a callback query to the bot when button is pressed, 1-64 bytes
+ * @method string       getSwitchInlineQuery()            Optional. If set, pressing the button will prompt the user to select one of their chats, open that chat and insert the bot's username and the specified inline query in the input field. Can be empty, in which case just the bot’s username will be inserted.
+ * @method string       getSwitchInlineQueryCurrentChat() Optional. If set, pressing the button will insert the bot‘s username and the specified inline query in the current chat's input field. Can be empty, in which case only the bot’s username will be inserted.
+ * @method CallbackGame getCallbackGame()                 Optional. Description of the game that will be launched when the user presses the button.
+ * @method bool         getPay()                          Optional. Specify True, to send a Pay button.
  *
  * @method $this setText(string $text)                                                     Label text on the button
  * @method $this setUrl(string $url)                                                       Optional. HTTP url to be opened when button is pressed
  * @method $this setCallbackData(string $callback_data)                                    Optional. Data to be sent in a callback query to the bot when button is pressed, 1-64 bytes
  * @method $this setSwitchInlineQuery(string $switch_inline_query)                         Optional. If set, pressing the button will prompt the user to select one of their chats, open that chat and insert the bot's username and the specified inline query in the input field. Can be empty, in which case just the bot’s username will be inserted.
  * @method $this setSwitchInlineQueryCurrentChat(string $switch_inline_query_current_chat) Optional. If set, pressing the button will insert the bot‘s username and the specified inline query in the current chat's input field. Can be empty, in which case only the bot’s username will be inserted.
+ * @method $this setCallbackGame(CallbackGame $callback_game)                              Optional. Description of the game that will be launched when the user presses the button.
  * @method $this setPay(bool $pay)                                                         Optional. Specify True, to send a Pay button.
  */
 class InlineKeyboardButton extends KeyboardButton
@@ -48,6 +50,7 @@ public static function couldBe($data)
                    array_key_exists('callback_data', $data) ||
                    array_key_exists('switch_inline_query', $data) ||
                    array_key_exists('switch_inline_query_current_chat', $data) ||
+                   array_key_exists('callback_game', $data) ||
                    array_key_exists('pay', $data)
                );
     }
@@ -63,14 +66,14 @@ protected function validate()
 
         $num_params = 0;
 
-        foreach (['url', 'callback_data', 'switch_inline_query', 'switch_inline_query_current_chat', 'pay'] as $param) {
+        foreach (['url', 'callback_data', 'switch_inline_query', 'switch_inline_query_current_chat', 'callback_game', 'pay'] as $param) {
             if ($this->getProperty($param, '') !== '') {
                 $num_params++;
             }
         }
 
         if ($num_params !== 1) {
-            throw new TelegramException('You must use only one of these fields: url, callback_data, switch_inline_query, switch_inline_query_current_chat, pay!');
+            throw new TelegramException('You must use only one of these fields: url, callback_data, switch_inline_query, switch_inline_query_current_chat, callback_game, pay!');
         }
     }
 
@@ -80,8 +83,8 @@ protected function validate()
     public function __call($method, $args)
     {
         // Only 1 of these can be set, so clear the others when setting a new one.
-        if (in_array($method, ['setUrl', 'setCallbackData', 'setSwitchInlineQuery', 'setSwitchInlineQueryCurrentChat', 'setPay'], true)) {
-            unset($this->url, $this->callback_data, $this->switch_inline_query, $this->switch_inline_query_current_chat, $this->pay);
+        if (in_array($method, ['setUrl', 'setCallbackData', 'setSwitchInlineQuery', 'setSwitchInlineQueryCurrentChat', 'setCallbackGame', 'setPay'], true)) {
+            unset($this->url, $this->callback_data, $this->switch_inline_query, $this->switch_inline_query_current_chat, $this->callback_game, $this->pay);
         }
 
         return parent::__call($method, $args);

src/Entities/InlineQuery/InlineQueryResultGame.php

@@ -0,0 +1,51 @@
+<?php
+/**
+ * This file is part of the TelegramBot package.
+ *
+ * (c) Avtandil Kikabidze aka LONGMAN <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Longman\TelegramBot\Entities\InlineQuery;
+
+use Longman\TelegramBot\Entities\InlineKeyboard;
+
+/**
+ * Class InlineQueryResultGame
+ *
+ * @link https://core.telegram.org/bots/api#inlinequeryresultgame
+ *
+ * <code>
+ * $data = [
+ *   'id'              => '',
+ *   'game_short_name' => '',
+ *   'reply_markup'    => <InlineKeyboard>,
+ * ];
+ * </code>
+ *
+ * @method string         getType()          Type of the result, must be game
+ * @method string         getId()            Unique identifier for this result, 1-64 bytes
+ * @method string         getGameShortName() Short name of the game
+ * @method InlineKeyboard getReplyMarkup()   Optional. Inline keyboard attached to the message
+ *
+ * @method $this setId(string $id)                            Unique identifier for this result, 1-64 bytes
+ * @method $this setGameShortName(string $game_short_name)    Short name of the game
+ * @method $this setReplyMarkup(InlineKeyboard $reply_markup) Optional. Inline keyboard attached to the message
+ */
+class InlineQueryResultGame extends InlineEntity implements InlineQueryResult
+{
+    /**
+     * InlineQueryResultGame constructor
+     *
+     * @param array $data
+     *
+     * @throws \Longman\TelegramBot\Exception\TelegramException
+     */
+    public function __construct(array $data = [])
+    {
+        $data['type'] = 'game';
+        parent::__construct($data);
+    }
+}

src/Entities/Message.php

@@ -10,6 +10,7 @@
 
 namespace Longman\TelegramBot\Entities;
 
+use Longman\TelegramBot\Entities\Games\Game;
 use Longman\TelegramBot\Entities\Payments\Invoice;
 use Longman\TelegramBot\Entities\Payments\SuccessfulPayment;
 
@@ -33,6 +34,7 @@
  * @method string            getAuthorSignature()       Optional. Signature of the post author for messages in channels
  * @method Audio             getAudio()                 Optional. Message is an audio file, information about the file
  * @method Document          getDocument()              Optional. Message is a general file, information about the file
+ * @method Game              getGame()                  Optional. Message is a game, information about the game.
  * @method Sticker           getSticker()               Optional. Message is a sticker, information about the sticker
  * @method Video             getVideo()                 Optional. Message is a video, information about the video
  * @method Voice             getVoice()                 Optional. Message is a voice message, information about the file
@@ -70,6 +72,7 @@ protected function subEntities()
             'caption_entities'   => MessageEntity::class,
             'audio'              => Audio::class,
             'document'           => Document::class,
+            'game'               => Game::class,
             'photo'              => PhotoSize::class,
             'sticker'            => Sticker::class,
             'video'              => Video::class,

src/Request.php

@@ -74,6 +74,9 @@
  * @method static ServerResponse sendInvoice(array $data)             Use this method to send invoices. On success, the sent Message is returned.
  * @method static ServerResponse answerShippingQuery(array $data)     If you sent an invoice requesting a shipping address and the parameter is_flexible was specified, the Bot API will send an Update with a shipping_query field to the bot. Use this method to reply to shipping queries. On success, True is returned.
  * @method static ServerResponse answerPreCheckoutQuery(array $data)  Once the user has confirmed their payment and shipping details, the Bot API sends the final confirmation in the form of an Update with the field pre_checkout_query. Use this method to respond to such pre-checkout queries. On success, True is returned.
+ * @method static ServerResponse sendGame(array $data)                Use this method to send a game. On success, the sent Message is returned.
+ * @method static ServerResponse setGameScore(array $data)            Use this method to set the score of the specified user in a game. On success, if the message was sent by the bot, returns the edited Message, otherwise returns True. Returns an error, if the new score is not greater than the user's current score in the chat and force is False.
+ * @method static ServerResponse getGameHighScores(array $data)       Use this method to get data for high score tables. Will return the score of the specified user and several of his neighbors in a game. On success, returns an Array of GameHighScore objects.
  */
 class Request
 {
@@ -185,6 +188,9 @@ class Request
         'sendInvoice',
         'answerShippingQuery',
         'answerPreCheckoutQuery',
+        'sendGame',
+        'setGameScore',
+        'getGameHighScores',
     ];
 
     /**
@@ -662,6 +668,8 @@ private static function limitTelegramRequests($action, array $data = [])
                 'sendVenue',
                 'sendContact',
                 'sendInvoice',
+                'sendGame',
+                'setGameScore',
                 'editMessageText',
                 'editMessageCaption',
                 'editMessageReplyMarkup',

structure.sql

@@ -81,6 +81,7 @@ CREATE TABLE IF NOT EXISTS `message` (
   `entities` TEXT COMMENT 'For text messages, special entities like usernames, URLs, bot commands, etc. that appear in the text',
   `audio` TEXT COMMENT 'Audio object. Message is an audio file, information about the file',
   `document` TEXT COMMENT 'Document object. Message is a general file, information about the file',
+  `game` TEXT COMMENT 'Game object. Message is a game, information about the game',
   `photo` TEXT COMMENT 'Array of PhotoSize objects. Message is a photo, available sizes of the photo',
   `sticker` TEXT COMMENT 'Sticker object. Message is a sticker, information about the sticker',
   `video` TEXT COMMENT 'Video object. Message is a video, information about the video',

utils/db-schema-update/0.51.0-unreleased.sql

@@ -0,0 +1 @@
+ALTER TABLE `message` ADD COLUMN `game` TEXT COMMENT 'Game object. Message is a game, information about the game' AFTER `document`;