Return an empty array for Entity properties with no items, instead of `null`

CHANGELOG.md

@@ -7,6 +7,7 @@ Exclamation symbols (:exclamation:) note something of importance e.g. breaking c
 ### Added
 ### Changed
 - Use PSR-12 for code style.
+- [:exclamation:][unreleased-bc] Return an empty array for Entity properties with no items, instead of `null`.
 ### Deprecated
 ### Removed
 ### Fixed
@@ -264,6 +265,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 @@ class DB
 
             $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 @@ class DB
             $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 @@ class DB
             $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 @@ class DB
             $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/Games/Game.php

@@ -47,13 +47,11 @@ class Game extends Entity
      * This method overrides the default getPhoto method
      * and returns a nice array of PhotoSize objects.
      *
-     * @return null|\Longman\TelegramBot\Entities\PhotoSize[]
+     * @return PhotoSize[]
      */
     public function getPhoto()
     {
-        $pretty_array = $this->makePrettyObjectArray(PhotoSize::class, 'photo');
-
-        return empty($pretty_array) ? null : $pretty_array;
+        return $this->makePrettyObjectArray(PhotoSize::class, 'photo');
     }
 
     /**
@@ -62,12 +60,10 @@ class Game extends Entity
      * This method overrides the default getTextEntities method
      * and returns a nice array of MessageEntity objects.
      *
-     * @return null|\Longman\TelegramBot\Entities\MessageEntity[]
+     * @return MessageEntity[]
      */
     public function getTextEntities()
     {
-        $pretty_array = $this->makePrettyObjectArray(MessageEntity::class, 'text_entities');
-
-        return empty($pretty_array) ? null : $pretty_array;
+        return $this->makePrettyObjectArray(MessageEntity::class, 'text_entities');
     }
 }

src/Entities/Message.php

@@ -118,13 +118,11 @@ class Message extends Entity
      * This method overrides the default getPhoto method
      * and returns a nice array of PhotoSize objects.
      *
-     * @return null|PhotoSize[]
+     * @return PhotoSize[]
      */
     public function getPhoto()
     {
-        $pretty_array = $this->makePrettyObjectArray(PhotoSize::class, 'photo');
-
-        return empty($pretty_array) ? null : $pretty_array;
+        return $this->makePrettyObjectArray(PhotoSize::class, 'photo');
     }
 
     /**
@@ -133,13 +131,11 @@ class Message extends Entity
      * This method overrides the default getNewChatPhoto method
      * and returns a nice array of PhotoSize objects.
      *
-     * @return null|PhotoSize[]
+     * @return PhotoSize[]
      */
     public function getNewChatPhoto()
     {
-        $pretty_array = $this->makePrettyObjectArray(PhotoSize::class, 'new_chat_photo');
-
-        return empty($pretty_array) ? null : $pretty_array;
+        return $this->makePrettyObjectArray(PhotoSize::class, 'new_chat_photo');
     }
 
     /**
@@ -148,13 +144,11 @@ class Message extends Entity
      * This method overrides the default getNewChatMembers method
      * and returns a nice array of User objects.
      *
-     * @return null|User[]
+     * @return User[]
      */
     public function getNewChatMembers()
     {
-        $pretty_array = $this->makePrettyObjectArray(User::class, 'new_chat_members');
-
-        return empty($pretty_array) ? null : $pretty_array;
+        return $this->makePrettyObjectArray(User::class, 'new_chat_members');
     }
 
     /**
@@ -163,13 +157,11 @@ class Message extends Entity
      * This method overrides the default getEntities method
      * and returns a nice array of MessageEntity objects.
      *
-     * @return null|MessageEntity[]
+     * @return MessageEntity[]
      */
     public function getEntities()
     {
-        $pretty_array = $this->makePrettyObjectArray(MessageEntity::class, 'entities');
-
-        return empty($pretty_array) ? null : $pretty_array;
+        return $this->makePrettyObjectArray(MessageEntity::class, 'entities');
     }
 
     /**
@@ -178,13 +170,11 @@ class Message extends Entity
      * This method overrides the default getCaptionEntities method
      * and returns a nice array of MessageEntity objects.
      *
-     * @return null|MessageEntity[]
+     * @return MessageEntity[]
      */
     public function getCaptionEntities()
     {
-        $pretty_array = $this->makePrettyObjectArray(MessageEntity::class, 'caption_entities');
-
-        return empty($pretty_array) ? null : $pretty_array;
+        return $this->makePrettyObjectArray(MessageEntity::class, 'caption_entities');
     }
 
     /**

src/Entities/Poll.php

@@ -39,12 +39,10 @@ class Poll extends Entity
      * This method overrides the default getOptions method
      * and returns a nice array of PollOption objects.
      *
-     * @return null|PollOption[]
+     * @return PollOption[]
      */
     public function getOptions()
     {
-        $pretty_array = $this->makePrettyObjectArray(PollOption::class, 'options');
-
-        return empty($pretty_array) ? null : $pretty_array;
+        return $this->makePrettyObjectArray(PollOption::class, 'options');
     }
 }

src/Entities/StickerSet.php

@@ -27,12 +27,10 @@ class StickerSet extends Entity
      * This method overrides the default getStickers method
      * and returns a nice array of Sticker objects.
      *
-     * @return null|Sticker[]
+     * @return Sticker[]
      */
     public function getStickers()
     {
-        $pretty_array = $this->makePrettyObjectArray(Sticker::class, 'stickers');
-
-        return empty($pretty_array) ? null : $pretty_array;
+        return $this->makePrettyObjectArray(Sticker::class, 'stickers');
     }
 }

src/Entities/TelegramPassport/EncryptedPassportElement.php

@@ -50,13 +50,11 @@ class EncryptedPassportElement extends Entity
      * This method overrides the default getFiles method
      * and returns a nice array of PassportFile objects.
      *
-     * @return null|PassportFile[]
+     * @return PassportFile[]
      */
     public function getFiles()
     {
-        $pretty_array = $this->makePrettyObjectArray(PassportFile::class, 'files');
-
-        return empty($pretty_array) ? null : $pretty_array;
+        return $this->makePrettyObjectArray(PassportFile::class, 'files');
     }
 
     /**
@@ -65,12 +63,10 @@ class EncryptedPassportElement extends Entity
      * This method overrides the default getTranslation method
      * and returns a nice array of PassportFile objects.
      *
-     * @return null|PassportFile[]
+     * @return PassportFile[]
      */
     public function getTranslation()
     {
-        $pretty_array = $this->makePrettyObjectArray(PassportFile::class, 'translation');
-
-        return empty($pretty_array) ? null : $pretty_array;
+        return $this->makePrettyObjectArray(PassportFile::class, 'translation');
     }
 }

src/Entities/TelegramPassport/PassportData.php

@@ -40,12 +40,10 @@ class PassportData extends Entity
      * This method overrides the default getData method
      * and returns a nice array of EncryptedPassportElement objects.
      *
-     * @return null|EncryptedPassportElement[]
+     * @return EncryptedPassportElement[]
      */
     public function getData()
     {
-        $pretty_array = $this->makePrettyObjectArray(EncryptedPassportElement::class, 'data');
-
-        return empty($pretty_array) ? null : $pretty_array;
+        return $this->makePrettyObjectArray(EncryptedPassportElement::class, 'data');
     }
 }