Smarten up subEntities and return empty array for Entity items

CHANGELOG.md

@@ -10,11 +10,13 @@ Exclamation symbols (:exclamation:) note something of importance e.g. breaking c
 ### Changed
 - Use PSR-12 for code style.
 - Some general housekeeping. (#972)
+- [:exclamation:][unreleased-bc] Return an empty array for Entity properties with no items, instead of `null`. (#969)
 ### Deprecated
 ### Removed
 - Botan.io integration completely removed.
 ### Fixed
 - `forward_date` is now correctly saved to the DB.
+- Broken `StickerSet::getStickers()` method.
 ### Security
 - Security disclosure managed by Tidelift.
 
@@ -269,6 +271,7 @@ Exclamation symbols (:exclamation:) note something of importance e.g. breaking c
 - Move `hideKeyboard` to `removeKeyboard`.
 
 [unreleased-sql-migration]: https://github.com/php-telegram-bot/core/tree/develop/utils/db-schema-update/unreleased.sql
+[unreleased-bc]: https://github.com/php-telegram-bot/core/wiki/Breaking-backwards-compatibility#unreleased
 [0.57.0-sql-migration]: https://github.com/php-telegram-bot/core/tree/master/utils/db-schema-update/0.56.0-0.57.0.sql
 [0.55.0-sql-migration]: https://github.com/php-telegram-bot/core/tree/master/utils/db-schema-update/0.54.1-0.55.0.sql
 [0.55.0-bc-move-animation-out-of-games-namespace]: https://github.com/php-telegram-bot/core/wiki/Breaking-backwards-compatibility#move-animation-out-of-games-namespace

src/DB.php

@@ -844,7 +844,7 @@ public static function insertPollRequest(Poll $poll)
 
             $sth->bindValue(':id', $poll->getId());
             $sth->bindValue(':question', $poll->getQuestion());
-            $sth->bindValue(':options', self::entitiesArrayToJson($poll->getOptions()));
+            $sth->bindValue(':options', self::entitiesArrayToJson($poll->getOptions() ?: null));
             $sth->bindValue(':is_closed', $poll->getIsClosed());
             $sth->bindValue(':created_at', self::getTimestamp());
 
@@ -976,13 +976,13 @@ public static function insertMessageRequest(Message $message)
             $sth->bindValue(':media_group_id', $message->getMediaGroupId());
             $sth->bindValue(':author_signature', $message->getAuthorSignature());
             $sth->bindValue(':text', $message->getText());
-            $sth->bindValue(':entities', self::entitiesArrayToJson($message->getEntities()));
-            $sth->bindValue(':caption_entities', self::entitiesArrayToJson($message->getCaptionEntities()));
+            $sth->bindValue(':entities', self::entitiesArrayToJson($message->getEntities() ?: null));
+            $sth->bindValue(':caption_entities', self::entitiesArrayToJson($message->getCaptionEntities() ?: null));
             $sth->bindValue(':audio', $message->getAudio());
             $sth->bindValue(':document', $message->getDocument());
             $sth->bindValue(':animation', $message->getAnimation());
             $sth->bindValue(':game', $message->getGame());
-            $sth->bindValue(':photo', self::entitiesArrayToJson($message->getPhoto()));
+            $sth->bindValue(':photo', self::entitiesArrayToJson($message->getPhoto() ?: null));
             $sth->bindValue(':sticker', $message->getSticker());
             $sth->bindValue(':video', $message->getVideo());
             $sth->bindValue(':voice', $message->getVoice());
@@ -995,7 +995,7 @@ public static function insertMessageRequest(Message $message)
             $sth->bindValue(':new_chat_members', $new_chat_members_ids);
             $sth->bindValue(':left_chat_member', $left_chat_member_id);
             $sth->bindValue(':new_chat_title', $message->getNewChatTitle());
-            $sth->bindValue(':new_chat_photo', self::entitiesArrayToJson($message->getNewChatPhoto()));
+            $sth->bindValue(':new_chat_photo', self::entitiesArrayToJson($message->getNewChatPhoto() ?: null));
             $sth->bindValue(':delete_chat_photo', $message->getDeleteChatPhoto());
             $sth->bindValue(':group_chat_created', $message->getGroupChatCreated());
             $sth->bindValue(':supergroup_chat_created', $message->getSupergroupChatCreated());
@@ -1058,7 +1058,7 @@ public static function insertEditedMessageRequest(Message $edited_message)
             $sth->bindValue(':user_id', $user_id);
             $sth->bindValue(':edit_date', $edit_date);
             $sth->bindValue(':text', $edited_message->getText());
-            $sth->bindValue(':entities', self::entitiesArrayToJson($edited_message->getEntities()));
+            $sth->bindValue(':entities', self::entitiesArrayToJson($edited_message->getEntities() ?: null));
             $sth->bindValue(':caption', $edited_message->getCaption());
 
             return $sth->execute();

src/Entities/CallbackQuery.php

@@ -30,7 +30,7 @@ class CallbackQuery extends Entity
     /**
      * {@inheritdoc}
      */
-    public function subEntities()
+    protected function subEntities()
     {
         return [
             'from'    => User::class,

src/Entities/Chat.php

@@ -46,7 +46,7 @@ class Chat extends Entity
     /**
      * {@inheritdoc}
      */
-    public function subEntities()
+    protected function subEntities()
     {
         return [
             'photo'          => ChatPhoto::class,

src/Entities/ChatMember.php

@@ -38,7 +38,7 @@ class ChatMember extends Entity
     /**
      * {@inheritdoc}
      */
-    public function subEntities()
+    protected function subEntities()
     {
         return [
             'user' => User::class,

src/Entities/Entity.php

@@ -138,7 +138,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,39 +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 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/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,102 +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
-     */
-    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 null|PhotoSize[]
-     */
-    public function getPhoto()
-    {
-        $pretty_array = $this->makePrettyObjectArray(PhotoSize::class, 'photo');
-
-        return empty($pretty_array) ? null : $pretty_array;
-    }
-
-    /**
-     * 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 null|PhotoSize[]
-     */
-    public function getNewChatPhoto()
-    {
-        $pretty_array = $this->makePrettyObjectArray(PhotoSize::class, 'new_chat_photo');
-
-        return empty($pretty_array) ? null : $pretty_array;
-    }
-
-    /**
-     * 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 null|User[]
-     */
-    public function getNewChatMembers()
-    {
-        $pretty_array = $this->makePrettyObjectArray(User::class, 'new_chat_members');
-
-        return empty($pretty_array) ? null : $pretty_array;
-    }
-
-    /**
-     * 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 null|MessageEntity[]
-     */
-    public function getEntities()
-    {
-        $pretty_array = $this->makePrettyObjectArray(MessageEntity::class, 'entities');
-
-        return empty($pretty_array) ? null : $pretty_array;
-    }
-
-    /**
-     * 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 null|MessageEntity[]
-     */
-    public function getCaptionEntities()
-    {
-        $pretty_array = $this->makePrettyObjectArray(MessageEntity::class, 'caption_entities');
-
-        return empty($pretty_array) ? null : $pretty_array;
-    }
-
     /**
      * return the entire command like /echo or /echo@bot1 if specified
      *

src/Entities/Payments/OrderInfo.php

@@ -29,7 +29,7 @@ class OrderInfo extends Entity
     /**
      * {@inheritdoc}
      */
-    public function subEntities()
+    protected function subEntities()
     {
         return [
             'shipping_address' => ShippingAddress::class,

src/Entities/Payments/PreCheckoutQuery.php

@@ -35,7 +35,7 @@ class PreCheckoutQuery extends Entity
     /**
      * {@inheritdoc}
      */
-    public function subEntities()
+    protected function subEntities()
     {
         return [
             'from'       => User::class,

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/Payments/ShippingQuery.php

@@ -32,7 +32,7 @@ class ShippingQuery extends Entity
     /**
      * {@inheritdoc}
      */
-    public function subEntities()
+    protected function subEntities()
     {
         return [
             'from'             => User::class,

src/Entities/Payments/SuccessfulPayment.php

@@ -32,7 +32,7 @@ class SuccessfulPayment extends Entity
     /**
      * {@inheritdoc}
      */
-    public function subEntities()
+    protected function subEntities()
     {
         return [
             'order_info' => OrderInfo::class,