#498 implement sendMediaGroup method

docs/12.features/7.attachments.md

@@ -213,3 +213,20 @@ Telegraph::document(Storage::path('brochure.pdf'))
     ->thumbnail(Storage::path('brochure_thumbnail.jpg'))
     ->send();
 ```
+
+### Media Group
+
+Group of photos, videos, documents or audios as an album can be sent through Telegraph `->mediaGroup()` method:
+
+```php
+Telegraph::mediaGroup([
+        [
+            'type' => 'photo',
+            'media' => 'https://my-repository/photo1.jpg',
+        ],
+        [
+            'type' => 'photo',
+            'media' => 'https://my-repository/photo2.jpg',
+        ]              
+])->send();
+```

docs/12.features/8.telegram-api-calls.md

@@ -220,6 +220,23 @@ sends a photo
 Telegraph::photo($pathToPhotoFile)->send();
 ```
 
+### Media Group
+
+sends a group of photos, videos, documents or audios as an album
+
+```php
+Telegraph::mediaGroup([
+        [
+            'type' => 'photo',
+            'media' => 'https://my-repository/photo1.jpg',
+        ],
+        [
+            'type' => 'photo',
+            'media' => 'https://my-repository/photo2.jpg',
+        ]              
+])->send();
+```
+
 ## registerBotCommands
 
 register commands in Telegram Bot in order to display them to the user when the "/" key is pressed

docs/13.models/2.telegraph-chat.md

@@ -598,3 +598,20 @@ $telegraphChat->setMenuButton()->default()->send(); //restore default
 $telegraphChat->setMenuButton()->commands()->send(); //show bot commands in menu button 
 $telegraphChat->setMenuButton()->webApp("Web App", "https://my-web.app")->send(); //show start web app button 
 ```
+
+### `Media Group`
+
+Group of photos, videos, documents or audios as an album can be sent through Telegraph `->mediaGroup()` method:
+
+```php
+$telegraphChat->mediaGroup([
+        [
+            'type' => 'photo',
+            'media' => 'https://my-repository/photo1.jpg',
+        ],
+        [
+            'type' => 'photo',
+            'media' => 'https://my-repository/photo2.jpg',
+        ]              
+])->send();
+```

src/Concerns/SendsAttachments.php

@@ -181,7 +181,7 @@ public function thumbnail(string $path): self
         $telegraph = clone $this;
 
         if (File::exists($path)) {
-            /* @phpstan-ignore-next-line  */
+            /* @phpstan-ignore-next-line */
             $maxSizeKb = floatval(config('telegraph.attachments.thumbnail.max_size_kb', 200));
 
             if (($size = $telegraph->fileSizeInKb($path)) > $maxSizeKb) {
@@ -236,6 +236,22 @@ public function photo(string $path, string $filename = null): self
         return $telegraph;
     }
 
+    /**
+     * @param array<int|string, array<mixed>> $mediaInputs
+     */
+    public function mediaGroup(array $mediaInputs): self
+    {
+        $telegraph = clone $this;
+
+        $telegraph->endpoint = self::ENDPOINT_SEND_MEDIA_GROUP;
+
+        $telegraph->data['chat_id'] = $telegraph->getChatId();
+
+        $telegraph->data['media'] = $mediaInputs;
+
+        return $telegraph;
+    }
+
     private function imageHeight(string $path): int
     {
         return $this->imageDimensions($path)[1];
@@ -292,7 +308,7 @@ public function dice(string $emoji = null): self
     protected function attachPhoto(self $telegraph, string $path, ?string $filename): void
     {
         if (File::exists($path)) {
-            /* @phpstan-ignore-next-line  */
+            /* @phpstan-ignore-next-line */
             $maxSizeInMb = floatval(config('telegraph.attachments.photo.max_size_mb', 10));
 
             if (($size = $telegraph->fileSizeInMb($path)) > $maxSizeInMb) {
@@ -310,7 +326,7 @@ protected function attachPhoto(self $telegraph, string $path, ?string $filename)
                 throw FileException::invalidPhotoSize($totalLength, $heightWidthSumPx);
             }
 
-            /* @phpstan-ignore-next-line  */
+            /* @phpstan-ignore-next-line */
             $maxRatio = floatval(config('telegraph.attachments.photo.max_ratio', 20));
 
             if (($ratio = $height / $width) > $maxRatio || $ratio < (1 / $maxRatio)) {
@@ -327,7 +343,7 @@ protected function attachPhoto(self $telegraph, string $path, ?string $filename)
     protected function attachAnimation(self $telegraph, string $path, ?string $filename): void
     {
         if (File::exists($path)) {
-            /* @phpstan-ignore-next-line  */
+            /* @phpstan-ignore-next-line */
             $maxSizeMb = floatval(config('telegraph.attachments.animation.max_size_mb', 50));
 
             if (($size = $telegraph->fileSizeInMb($path)) > $maxSizeMb) {
@@ -347,7 +363,7 @@ protected function attachAnimation(self $telegraph, string $path, ?string $filen
     protected function attachVideo(self $telegraph, string $path, ?string $filename): void
     {
         if (File::exists($path)) {
-            /* @phpstan-ignore-next-line  */
+            /* @phpstan-ignore-next-line */
             $maxSizeMb = floatval(config('telegraph.attachments.video.max_size_mb', 50));
 
             if (($size = $telegraph->fileSizeInMb($path)) > $maxSizeMb) {
@@ -374,7 +390,7 @@ protected function attachVideo(self $telegraph, string $path, ?string $filename)
     protected function attachAudio(self $telegraph, string $path, ?string $filename): void
     {
         if (File::exists($path)) {
-            /* @phpstan-ignore-next-line  */
+            /* @phpstan-ignore-next-line */
             $maxSizeMb = floatval(config('telegraph.attachments.audio.max_size_mb', 50));
 
             if (($size = $telegraph->fileSizeInMb($path)) > $maxSizeMb) {
@@ -398,8 +414,7 @@ protected function attachAudio(self $telegraph, string $path, ?string $filename)
     protected function attachDocument(self $telegraph, string $path, ?string $filename): void
     {
         if (File::exists($path)) {
-
-            /* @phpstan-ignore-next-line  */
+            /* @phpstan-ignore-next-line */
             $maxSizeMb = floatval(config('telegraph.attachments.document.max_size_mb', 50));
 
             if (($size = $telegraph->fileSizeInMb($path)) > $maxSizeMb) {

src/DTO/InlineQueryResultArticle.php

@@ -108,7 +108,7 @@ public function data(): array
             'thumb_height' => $this->thumbHeight,
         ];
 
-        if($this->message !== null) {
+        if ($this->message !== null) {
             $data['input_message_content'] = [
                 'message_text' => $this->message,
                 'parse_mode' => $this->parseMode ?? config('telegraph.default_parse_mode', Telegraph::PARSE_HTML),

src/DTO/InlineQueryResultContact.php

@@ -102,7 +102,7 @@ public function data(): array
             'thumb_height' => $this->thumbHeight,
         ];
 
-        if($this->message !== null) {
+        if ($this->message !== null) {
             $data['input_message_content'] = [
                 'message_text' => $this->message,
                 'parse_mode' => $this->parseMode ?? config('telegraph.default_parse_mode', Telegraph::PARSE_HTML),

src/DTO/InlineQueryResultLocation.php

@@ -123,7 +123,7 @@ public function data(): array
             'horizontal_accuracy' => $this->horizontalAccuracy,
         ];
 
-        if($this->message !== null) {
+        if ($this->message !== null) {
             $data['input_message_content'] = [
                 'message_text' => $this->message,
                 'parse_mode' => $this->parseMode ?? config('telegraph.default_parse_mode', Telegraph::PARSE_HTML),

src/Facades/Telegraph.php

@@ -49,6 +49,7 @@
  * @method static \DefStudio\Telegraph\Telegraph  video(string $path, string $filename = null)
  * @method static \DefStudio\Telegraph\Telegraph  audio(string $path, string $filename = null)
  * @method static \DefStudio\Telegraph\Telegraph  dice()
+ * @method static \DefStudio\Telegraph\Telegraph  mediaGroup(string $path, array $media)
  * @method static \DefStudio\Telegraph\Telegraph  botUpdates()
  * @method static \DefStudio\Telegraph\Telegraph  botInfo()
  * @method static \DefStudio\Telegraph\Telegraph  setBaseUrl(string|null $url)

src/Models/TelegraphChat.php

@@ -223,6 +223,14 @@ public function photo(string $path, string $filename = null): Telegraph
         return TelegraphFacade::chat($this)->photo($path, $filename);
     }
 
+    /**
+     * @param array<int|string, array<mixed>> $media
+     */
+    public function mediaGroup(array $media): Telegraph
+    {
+        return TelegraphFacade::chat($this)->mediaGroup($media);
+    }
+
     public function animation(string $path, string $filename = null): Telegraph
     {
         return TelegraphFacade::chat($this)->animation($path, $filename);

src/Telegraph.php

@@ -69,6 +69,7 @@ class Telegraph
     public const ENDPOINT_SEND_LOCATION = 'sendLocation';
     public const ENDPOINT_SEND_ANIMATION = 'sendAnimation';
     public const ENDPOINT_SEND_VOICE = 'sendVoice';
+    public const ENDPOINT_SEND_MEDIA_GROUP = 'sendMediaGroup';
     public const ENDPOINT_SEND_CHAT_ACTION = 'sendChatAction';
     public const ENDPOINT_SEND_DOCUMENT = 'sendDocument';
     public const ENDPOINT_SEND_PHOTO = 'sendPhoto';

tests/TestCase.php

@@ -33,7 +33,6 @@ public function getEnvironmentSetUp($app): void
         $this->filesystemSetup($app['config']);
 
         $app['config']->set('database.default', 'testing');
-
     }
 
     protected function defineDatabaseMigrations(): void

tests/Unit/Concerns/HasBotsAndChatsTest.php

@@ -107,7 +107,6 @@
 });
 
 test('photo is validated', function (string $path, bool $valid, string $exceptionClass = null, string $exceptionMessage = null, array $customConfigs = []) {
-
     foreach ($customConfigs as $key => $value) {
         Config::set($key, $value);
     }

tests/Unit/Concerns/SendsAttachmentsTest.php

@@ -85,7 +85,6 @@
 });
 
 test('documents are validated', function (string $path, bool $valid, string $exceptionClass = null, string $exceptionMessage = null, array $customConfigs = []) {
-
     foreach ($customConfigs as $key => $value) {
         Config::set($key, $value);
     }
@@ -337,7 +336,6 @@
 });
 
 test('photos are validated', function (string $path, bool $valid, string $exceptionClass = null, string $exceptionMessage = null, array $customConfigs = []) {
-
     foreach ($customConfigs as $key => $value) {
         Config::set($key, $value);
     }

tests/Unit/Handlers/WebhookHandlerTest.php

@@ -358,7 +358,6 @@
 });
 
 it('does not crash on errors', function () {
-
     $chat = chat();
 
     Facade::fake();

tests/Unit/Models/TelegraphChatTest.php

@@ -749,3 +749,32 @@
         'caption' => 'test',
     ]);
 });
+
+it('can send a mediaGroup from remote url', function () {
+    Telegraph::fake();
+    $chat = make_chat();
+
+    $chat->mediaGroup([
+        [
+            'type' => 'photo',
+            'media' => 'https://test.dev/photo.jpg',
+        ],
+        [
+            'type' => 'photo',
+            'media' => 'https://test.dev/photo.jpg',
+        ],
+    ])->send();
+
+    Telegraph::assertSentData(\DefStudio\Telegraph\Telegraph::ENDPOINT_SEND_MEDIA_GROUP, [
+        'media' => [
+            [
+                'type' => 'photo',
+                'media' => 'https://test.dev/photo.jpg',
+            ],
+            [
+                'type' => 'photo',
+                'media' => 'https://test.dev/photo.jpg',
+            ],
+        ],
+    ]);
+});