Simplify the process of getting arrays of items from Entities.

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 @@ abstract class Entity
                 $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 @@ use Longman\TelegramBot\Entities\PhotoSize;
  *
  * @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 @@ use Longman\TelegramBot\Entities\TelegramPassport\PassportData;
  * @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 @@ use Longman\TelegramBot\Entities\TelegramPassport\PassportData;
  * @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 @@ class Message extends Entity
             '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,9 +94,9 @@ class Message extends Entity
             '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,
@@ -99,84 +104,6 @@ class Message extends Entity
         ];
     }
 
-    /**
-     * 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 @@ class Message extends Entity
      * Bot added in chat
      *
      * @return bool
-     * @throws \Longman\TelegramBot\Exception\TelegramException
      */
     public function botAddedInChat()
     {

src/Entities/Payments/ShippingOption.php

@@ -19,8 +19,9 @@ use Longman\TelegramBot\Entities\Entity;
  *
  * @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 @@ namespace Longman\TelegramBot\Entities;
  *
  * @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 @@ namespace Longman\TelegramBot\Entities;
  *
  * @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],
+        ];
     }
 }

src/Entities/TelegramPassport/EncryptedPassportElement.php

@@ -19,14 +19,16 @@ use Longman\TelegramBot\Entities\Entity;
  *
  * @link https://core.telegram.org/bots/api#encryptedpassportelement
  *
- * @method string       getType()        Element type. One of “personal_details”, “passport”, “driver_license”, “identity_card”, “internal_passport”, “address”, “utility_bill”, “bank_statement”, “rental_agreement”, “passport_registration”, “temporary_registration”, “phone_number”, “email”.
- * @method string       getData()        Optional. Base64-encoded encrypted Telegram Passport element data provided by the user, available for “personal_details”, “passport”, “driver_license”, “identity_card”, “identity_passport” and “address” types. Can be decrypted and verified using the accompanying EncryptedCredentials.
- * @method string       getPhoneNumber() Optional. User's verified phone number, available only for “phone_number” type
- * @method string       getEmail()       Optional. User's verified email address, available only for “email” type
- * @method PassportFile getFrontSide()   Optional. Encrypted file with the front side of the document, provided by the user. Available for “passport”, “driver_license”, “identity_card” and “internal_passport”. The file can be decrypted and verified using the accompanying EncryptedCredentials.
- * @method PassportFile getReverseSide() Optional. Encrypted file with the reverse side of the document, provided by the user. Available for “driver_license” and “identity_card”. The file can be decrypted and verified using the accompanying EncryptedCredentials.
- * @method PassportFile getSelfie()      Optional. Encrypted file with the selfie of the user holding a document, provided by the user; available for “passport”, “driver_license”, “identity_card” and “internal_passport”. The file can be decrypted and verified using the accompanying EncryptedCredentials.
- * @method string       getHash()        Base64-encoded element hash for using in PassportElementErrorUnspecified
+ * @method string         getType()        Element type. One of “personal_details”, “passport”, “driver_license”, “identity_card”, “internal_passport”, “address”, “utility_bill”, “bank_statement”, “rental_agreement”, “passport_registration”, “temporary_registration”, “phone_number”, “email”.
+ * @method string         getData()        Optional. Base64-encoded encrypted Telegram Passport element data provided by the user, available for “personal_details”, “passport”, “driver_license”, “identity_card”, “identity_passport” and “address” types. Can be decrypted and verified using the accompanying EncryptedCredentials.
+ * @method string         getPhoneNumber() Optional. User's verified phone number, available only for “phone_number” type
+ * @method string         getEmail()       Optional. User's verified email address, available only for “email” type
+ * @method PassportFile[] getFiles()       Optional. Array of encrypted files with documents provided by the user, available for “utility_bill”, “bank_statement”, “rental_agreement”, “passport_registration” and “temporary_registration” types. Files can be decrypted and verified using the accompanying EncryptedCredentials.
+ * @method PassportFile   getFrontSide()   Optional. Encrypted file with the front side of the document, provided by the user. Available for “passport”, “driver_license”, “identity_card” and “internal_passport”. The file can be decrypted and verified using the accompanying EncryptedCredentials.
+ * @method PassportFile   getReverseSide() Optional. Encrypted file with the reverse side of the document, provided by the user. Available for “driver_license” and “identity_card”. The file can be decrypted and verified using the accompanying EncryptedCredentials.
+ * @method PassportFile   getSelfie()      Optional. Encrypted file with the selfie of the user holding a document, provided by the user; available for “passport”, “driver_license”, “identity_card” and “internal_passport”. The file can be decrypted and verified using the accompanying EncryptedCredentials.
+ * @method PassportFile[] getTranslation() Optional. Array of encrypted files with translated versions of documents provided by the user. Available if requested for “passport”, “driver_license”, “identity_card”, “internal_passport”, “utility_bill”, “bank_statement”, “rental_agreement”, “passport_registration” and “temporary_registration” types. Files can be decrypted and verified using the accompanying EncryptedCredentials.
+ * @method string         getHash()        Base64-encoded element hash for using in PassportElementErrorUnspecified
  **/
 class EncryptedPassportElement extends Entity
 {
@@ -36,37 +38,11 @@ class EncryptedPassportElement extends Entity
     protected function subEntities()
     {
         return [
-            'files'        => PassportFile::class,
+            'files'        => [PassportFile::class],
             'front_side'   => PassportFile::class,
             'reverse_side' => PassportFile::class,
             'selfie'       => PassportFile::class,
-            'translation'  => PassportFile::class,
+            'translation'  => [PassportFile::class],
         ];
     }
-
-    /**
-     * Optional. Array of encrypted files with documents provided by the user, available for “utility_bill”, “bank_statement”, “rental_agreement”, “passport_registration” and “temporary_registration” types. Files can be decrypted and verified using the accompanying EncryptedCredentials.
-     *
-     * This method overrides the default getFiles method
-     * and returns a nice array of PassportFile objects.
-     *
-     * @return PassportFile[]
-     */
-    public function getFiles()
-    {
-        return $this->makePrettyObjectArray(PassportFile::class, 'files');
-    }
-
-    /**
-     * Optional. Array of encrypted files with translated versions of documents provided by the user. Available if requested for “passport”, “driver_license”, “identity_card”, “internal_passport”, “utility_bill”, “bank_statement”, “rental_agreement”, “passport_registration” and “temporary_registration” types. Files can be decrypted and verified using the accompanying EncryptedCredentials.
-     *
-     * This method overrides the default getTranslation method
-     * and returns a nice array of PassportFile objects.
-     *
-     * @return PassportFile[]
-     */
-    public function getTranslation()
-    {
-        return $this->makePrettyObjectArray(PassportFile::class, 'translation');
-    }
 }

src/Entities/TelegramPassport/PassportData.php

@@ -19,7 +19,8 @@ use Longman\TelegramBot\Entities\Entity;
  *
  * @link https://core.telegram.org/bots/api#passportdata
  *
- * @method EncryptedCredentials getCredentials() Encrypted credentials required to decrypt the data
+ * @method EncryptedPassportElement[] getData()        Array with information about documents and other Telegram Passport elements that was shared with the bot
+ * @method EncryptedCredentials       getCredentials() Encrypted credentials required to decrypt the data
  **/
 class PassportData extends Entity
 {
@@ -29,21 +30,8 @@ class PassportData extends Entity
     protected function subEntities()
     {
         return [
-            'data'        => EncryptedPassportElement::class,
+            'data'        => [EncryptedPassportElement::class],
             'credentials' => EncryptedCredentials::class,
         ];
     }
-
-    /**
-     * Array with information about documents and other Telegram Passport elements that was shared with the bot
-     *
-     * This method overrides the default getData method
-     * and returns a nice array of EncryptedPassportElement objects.
-     *
-     * @return EncryptedPassportElement[]
-     */
-    public function getData()
-    {
-        return $this->makePrettyObjectArray(EncryptedPassportElement::class, 'data');
-    }
 }