Simplify the process of getting arrays of items from Entities.

Author: noplanman

CHANGELOG.md

@@ -12,6 +12,7 @@ Exclamation symbols (:exclamation:) note something of importance e.g. breaking c
 ### Removed
 ### Fixed
 - `forward_date` is now correctly saved to the DB.
+- Broken `StickerSet::getStickers()` method.
 ### Security
 
 ## [0.57.0] - 2019-06-01

src/Entities/Entity.php

@@ -142,7 +142,13 @@ public function __call($method, $args)
                 $sub_entities = $this->subEntities();
 
                 if (isset($sub_entities[$property_name])) {
-                    return new $sub_entities[$property_name]($property, $this->getProperty('bot_username'));
+                    $class = $sub_entities[$property_name];
+
+                    if (is_array($class)) {
+                        return $this->makePrettyObjectArray(reset($class), $property_name);
+                    }
+
+                    return new $class($property, $this->getProperty('bot_username'));
                 }
 
                 return $property;

src/Entities/Games/Game.php

@@ -22,10 +22,12 @@
  *
  * @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
+ * @method string          getTitle()        Title of the game
+ * @method string          getDescription()  Description of the game
+ * @method PhotoSize[]     getPhoto()        Photo that will be displayed in the game message in chats.
+ * @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 MessageEntity[] getTextEntities() Optional. Special entities that appear in text, such as usernames, URLs, bot commands, etc.
+ * @method Animation       getAnimation()    Optional. Animation that will be displayed in the game message in chats. Upload via BotFather
  **/
 class Game extends Entity
 {
@@ -35,35 +37,9 @@ class Game extends Entity
     protected function subEntities()
     {
         return [
-            'photo'         => PhotoSize::class,
-            'text_entities' => MessageEntity::class,
+            '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 PhotoSize[]
-     */
-    public function getPhoto()
-    {
-        return $this->makePrettyObjectArray(PhotoSize::class, 'photo');
-    }
-
-    /**
-     * 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 MessageEntity[]
-     */
-    public function getTextEntities()
-    {
-        return $this->makePrettyObjectArray(MessageEntity::class, 'text_entities');
-    }
 }

src/Entities/Message.php

@@ -34,10 +34,13 @@
  * @method int               getEditDate()              Optional. Date the message was last edited in Unix time
  * @method string            getMediaGroupId()          Optional. The unique identifier of a media message group this message belongs to
  * @method string            getAuthorSignature()       Optional. Signature of the post author for messages in channels
+ * @method MessageEntity[]   getEntities()              Optional. For text messages, special entities like usernames, URLs, bot commands, etc. that appear in the text
+ * @method MessageEntity[]   getCaptionEntities()       Optional. For messages with a caption, special entities like usernames, URLs, bot commands, etc. that appear in the caption
  * @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 Animation         getAnimation()             Optional. Message is an animation, information about the animation. For backward compatibility, when this field is set, the document field will also be set
  * @method Game              getGame()                  Optional. Message is a game, information about the game.
+ * @method PhotoSize[]       getPhoto()                 Optional. Message is a photo, available sizes of the photo
  * @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
@@ -47,8 +50,10 @@
  * @method Location          getLocation()              Optional. Message is a shared location, information about the location
  * @method Venue             getVenue()                 Optional. Message is a venue, information about the venue
  * @method Poll              getPoll()                  Optional. Message is a native poll, information about the poll
+ * @method User[]            getNewChatMembers()        Optional. A new member(s) was added to the group, information about them (one of this members may be the bot itself)
  * @method User              getLeftChatMember()        Optional. A member was removed from the group, information about them (this member may be the bot itself)
  * @method string            getNewChatTitle()          Optional. A chat title was changed to this value
+ * @method PhotoSize[]       getNewChatPhoto()          Optional. A chat photo was changed to this value
  * @method bool              getDeleteChatPhoto()       Optional. Service message: the chat photo was deleted
  * @method bool              getGroupChatCreated()      Optional. Service message: the group has been created
  * @method bool              getSupergroupChatCreated() Optional. Service message: the supergroup has been created. This field can't be received in a message coming through updates, because bot can’t be a member of a supergroup when it is created. It can only be found in reply_to_message if someone replies to a very first message in a directly created supergroup.
@@ -74,13 +79,13 @@ protected function subEntities()
             'forward_from'       => User::class,
             'forward_from_chat'  => Chat::class,
             'reply_to_message'   => ReplyToMessage::class,
-            'entities'           => MessageEntity::class,
-            'caption_entities'   => MessageEntity::class,
+            'entities'           => [MessageEntity::class],
+            'caption_entities'   => [MessageEntity::class],
             'audio'              => Audio::class,
             'document'           => Document::class,
             'animation'          => Animation::class,
             'game'               => Game::class,
-            'photo'              => PhotoSize::class,
+            'photo'              => [PhotoSize::class],
             'sticker'            => Sticker::class,
             'video'              => Video::class,
             'voice'              => Voice::class,
@@ -89,94 +94,16 @@ protected function subEntities()
             'location'           => Location::class,
             'venue'              => Venue::class,
             'poll'               => Poll::class,
-            'new_chat_members'   => User::class,
+            'new_chat_members'   => [User::class],
             'left_chat_member'   => User::class,
-            'new_chat_photo'     => PhotoSize::class,
+            'new_chat_photo'     => [PhotoSize::class],
             'pinned_message'     => Message::class,
             'invoice'            => Invoice::class,
             'successful_payment' => SuccessfulPayment::class,
             'passport_data'      => PassportData::class,
         ];
     }
 
-    /**
-     * Message constructor
-     *
-     * @param array  $data
-     * @param string $bot_username
-     *
-     * @throws \Longman\TelegramBot\Exception\TelegramException
-     */
-    public function __construct(array $data, $bot_username = '')
-    {
-        parent::__construct($data, $bot_username);
-    }
-
-    /**
-     * Optional. Message is a photo, available sizes of the photo
-     *
-     * This method overrides the default getPhoto method
-     * and returns a nice array of PhotoSize objects.
-     *
-     * @return PhotoSize[]
-     */
-    public function getPhoto()
-    {
-        return $this->makePrettyObjectArray(PhotoSize::class, 'photo');
-    }
-
-    /**
-     * Optional. A chat photo was changed to this value
-     *
-     * This method overrides the default getNewChatPhoto method
-     * and returns a nice array of PhotoSize objects.
-     *
-     * @return PhotoSize[]
-     */
-    public function getNewChatPhoto()
-    {
-        return $this->makePrettyObjectArray(PhotoSize::class, 'new_chat_photo');
-    }
-
-    /**
-     * Optional. A new member(s) was added to the group, information about them (one of this members may be the bot itself)
-     *
-     * This method overrides the default getNewChatMembers method
-     * and returns a nice array of User objects.
-     *
-     * @return User[]
-     */
-    public function getNewChatMembers()
-    {
-        return $this->makePrettyObjectArray(User::class, 'new_chat_members');
-    }
-
-    /**
-     * Optional. For text messages, special entities like usernames, URLs, bot commands, etc. that appear in the text
-     *
-     * This method overrides the default getEntities method
-     * and returns a nice array of MessageEntity objects.
-     *
-     * @return MessageEntity[]
-     */
-    public function getEntities()
-    {
-        return $this->makePrettyObjectArray(MessageEntity::class, 'entities');
-    }
-
-    /**
-     * Optional. For messages with a caption, special entities like usernames, URLs, bot commands, etc. that appear in the caption
-     *
-     * This method overrides the default getCaptionEntities method
-     * and returns a nice array of MessageEntity objects.
-     *
-     * @return MessageEntity[]
-     */
-    public function getCaptionEntities()
-    {
-        return $this->makePrettyObjectArray(MessageEntity::class, 'caption_entities');
-    }
-
     /**
      * return the entire command like /echo or /echo@bot1 if specified
      *
@@ -254,7 +181,6 @@ public function getText($without_cmd = false)
      * Bot added in chat
      *
      * @return bool
-     * @throws \Longman\TelegramBot\Exception\TelegramException
      */
     public function botAddedInChat()
     {

src/Entities/Payments/ShippingOption.php

@@ -19,8 +19,9 @@
  *
  * @link https://core.telegram.org/bots/api#shippingoption
  *
- * @method string getId()    Shipping option identifier
- * @method string getTitle() Option title
+ * @method string         getId()     Shipping option identifier
+ * @method string         getTitle()  Option title
+ * @method LabeledPrice[] getPrices() List of price portions
  **/
 class ShippingOption extends Entity
 {
@@ -30,19 +31,7 @@ class ShippingOption extends Entity
     protected function subEntities()
     {
         return [
-            'prices' => LabeledPrice::class,
+            'prices' => [LabeledPrice::class],
         ];
     }
-
-    /**
-     * List of price portions
-     *
-     * This method overrides the default getPrices method and returns a nice array
-     *
-     * @return LabeledPrice[]
-     */
-    public function getPrices()
-    {
-        return $this->makePrettyObjectArray(LabeledPrice::class, 'prices');
-    }
 }

src/Entities/Poll.php

@@ -17,9 +17,10 @@
  *
  * @link https://core.telegram.org/bots/api#poll
  *
- * @method string getId()       Unique poll identifier
- * @method string getQuestion() Poll question, 1-255 characters
- * @method bool   getIsClosed() True, if the poll is closed
+ * @method string       getId()       Unique poll identifier
+ * @method string       getQuestion() Poll question, 1-255 characters
+ * @method PollOption[] getOptions()  List of poll options
+ * @method bool         getIsClosed() True, if the poll is closed
  */
 class Poll extends Entity
 {
@@ -29,20 +30,7 @@ class Poll extends Entity
     protected function subEntities()
     {
         return [
-            'options' => PollOption::class,
+            'options' => [PollOption::class],
         ];
     }
-
-    /**
-     * List of poll options
-     *
-     * This method overrides the default getOptions method
-     * and returns a nice array of PollOption objects.
-     *
-     * @return PollOption[]
-     */
-    public function getOptions()
-    {
-        return $this->makePrettyObjectArray(PollOption::class, 'options');
-    }
 }

src/Entities/StickerSet.php

@@ -15,22 +15,20 @@
  *
  * @link https://core.telegram.org/bots/api#stickerset
  *
- * @method string getName()          Sticker set name
- * @method string getTitle()         Sticker set title
- * @method bool   getContainsMasks() True, if the sticker set contains masks
+ * @method string    getName()          Sticker set name
+ * @method string    getTitle()         Sticker set title
+ * @method bool      getContainsMasks() True, if the sticker set contains masks
+ * @method Sticker[] getStickers()      List of all set stickers
  */
 class StickerSet extends Entity
 {
     /**
-     * List of all set stickers
-     *
-     * This method overrides the default getStickers method
-     * and returns a nice array of Sticker objects.
-     *
-     * @return Sticker[]
+     * {@inheritdoc}
      */
-    public function getStickers()
+    protected function subEntities()
     {
-        return $this->makePrettyObjectArray(Sticker::class, 'stickers');
+        return [
+            'stickers' => [Sticker::class],
+        ];
     }
 }