symfony · fabpot · Oct 10, 2023 · Sep 22, 2023
@@ -1,6 +1,12 @@
 CHANGELOG
 =========
 
+6.4
+---
+
+ * Add support for `sendLocation`, `sendAudio`, `sendDocument`, `sendVideo`, `sendAnimation`, `sendVenue`, `sendContact` and `sendSticker` API methods
+ * Add support for sending local files
+
 6.3
 ---
 

@@ -47,15 +47,109 @@ $chatMessage->options($telegramOptions);
 $chatter->send($chatMessage);
 ```
 
-Adding Photo to a Message
+Adding files to a Message
 -------------------------
 
 With a Telegram message, you can use the `TelegramOptions` class to add
 [message options](https://core.telegram.org/bots/api).
 
+> :warning: **WARNING**
+In one message you can send only one file
+
+[Telegram supports 3 ways](https://core.telegram.org/bots/api#sending-files) for passing files:
+
+ * You can send files by passing public http url to option:
+   * Photo
+     ```php
+     $telegramOptions = (new TelegramOptions())
+          ->photo('https://localhost/photo.mp4');
+     ```
+   * Video
+     ```php
+     $telegramOptions = (new TelegramOptions())
+          ->video('https://localhost/video.mp4');
+     ```
+   * Animation
+     ```php
+     $telegramOptions = (new TelegramOptions())
+          ->animation('https://localhost/animation.gif');
+     ```
+   * Audio
+     ```php
+     $telegramOptions = (new TelegramOptions())
+          ->audio('https://localhost/audio.ogg');
+     ```
+   * Document
+     ```php
+     $telegramOptions = (new TelegramOptions())
+          ->document('https://localhost/document.odt');
+     ```
+   * Sticker
+     ```php
+     $telegramOptions = (new TelegramOptions())
+          ->sticker('https://localhost/sticker.webp', '🤖');
+     ```
+ * You can send files by passing local path to option, in this case file will be sent via multipart/form-data:
+    * Photo
+      ```php
+      $telegramOptions = (new TelegramOptions())
+           ->uploadPhoto('files/photo.png');
+      ```
+    * Video
+      ```php
+      $telegramOptions = (new TelegramOptions())
+           ->uploadVideo('files/video.mp4');
+      ```
+    * Animation
+      ```php
+          $telegramOptions = (new TelegramOptions())
+               ->uploadAnimation('files/animation.gif');
+      ```
+    * Audio
+      ```php
+      $telegramOptions = (new TelegramOptions())
+           ->uploadAudio('files/audio.ogg');
+      ```
+    * Document
+      ```php
+      $telegramOptions = (new TelegramOptions())
+           ->uploadDocument('files/document.odt');
+      ```
+    * Sticker
+      ```php
+      $telegramOptions = (new TelegramOptions())
+           ->uploadSticker('files/sticker.webp', '🤖');
+      ```
+ * You can send files by passing file_id to option:
+   * Photo
+     ```php
+     $telegramOptions = (new TelegramOptions())
+          ->photo('ABCDEF');
+     ```
+   * Video
+     ```php
+     $telegramOptions = (new TelegramOptions())
+          ->video('ABCDEF');
+     ```
+   * Animation
+     ```php
+     $telegramOptions = (new TelegramOptions())
+          ->animation('ABCDEF');
+     ```
+   * Audio
+     ```php
+     $telegramOptions = (new TelegramOptions())
+          ->audio('ABCDEF');
+     ```
+   * Document
+     ```php
+     $telegramOptions = (new TelegramOptions())
+          ->document('ABCDEF');
+     ```
+   * Sticker - *Can't be sent using file_id*
+
+Full example:
 ```php
-use Symfony\Component\Notifier\Bridge\Telegram\Reply\Markup\Button\InlineKeyboardButton;
-use Symfony\Component\Notifier\Bridge\Telegram\Reply\Markup\InlineKeyboardMarkup;
 use Symfony\Component\Notifier\Bridge\Telegram\TelegramOptions;
 use Symfony\Component\Notifier\Message\ChatMessage;
 
@@ -76,6 +170,86 @@ $chatMessage->options($telegramOptions);
 $chatter->send($chatMessage);
 ```
 
+Adding Location to a Message
+----------------------------
+
+With a Telegram message, you can use the `TelegramOptions` class to add
+[message options](https://core.telegram.org/bots/api).
+
+```php
+use Symfony\Component\Notifier\Bridge\Telegram\TelegramOptions;
+use Symfony\Component\Notifier\Message\ChatMessage;
+
+$chatMessage = new ChatMessage('');
+
+// Create Telegram options
+$telegramOptions = (new TelegramOptions())
+    ->chatId('@symfonynotifierdev')
+    ->parseMode('MarkdownV2')
+    ->location(48.8566, 2.3522);
+
+// Add the custom options to the chat message and send the message
+$chatMessage->options($telegramOptions);
+
+$chatter->send($chatMessage);
+```
+
+Adding Venue to a Message
+----------------------------
+
+With a Telegram message, you can use the `TelegramOptions` class to add
+[message options](https://core.telegram.org/bots/api).
+
+```php
+use Symfony\Component\Notifier\Bridge\Telegram\TelegramOptions;
+use Symfony\Component\Notifier\Message\ChatMessage;
+
+$chatMessage = new ChatMessage('');
+
+// Create Telegram options
+$telegramOptions = (new TelegramOptions())
+    ->chatId('@symfonynotifierdev')
+    ->parseMode('MarkdownV2')
+    ->venue(48.8566, 2.3522, 'Center of Paris', 'France, Paris');
+
+// Add the custom options to the chat message and send the message
+$chatMessage->options($telegramOptions);
+
+$chatter->send($chatMessage);
+```
+
+Adding Contact to a Message
+----------------------------
+
+With a Telegram message, you can use the `TelegramOptions` class to add
+[message options](https://core.telegram.org/bots/api).
+
+```php
+use Symfony\Component\Notifier\Bridge\Telegram\TelegramOptions;
+use Symfony\Component\Notifier\Message\ChatMessage;
+
+$chatMessage = new ChatMessage('');
+
+$vCard = 'BEGIN:VCARD
+VERSION:3.0
+N:Doe;John;;;
+FN:John Doe
+EMAIL;type=INTERNET;type=WORK;type=pref:[email protected]
+TEL;type=WORK;type=pref:+330186657200
+END:VCARD';
+
+// Create Telegram options
+$telegramOptions = (new TelegramOptions())
+    ->chatId('@symfonynotifierdev')
+    ->parseMode('MarkdownV2')
+    ->contact('+330186657200', 'John', 'Doe', $vCard);
+
+// Add the custom options to the chat message and send the message
+$chatMessage->options($telegramOptions);
+
+$chatter->send($chatMessage);
+```
+
 Updating Messages
 -----------------
 

@@ -112,6 +112,16 @@ public function photo(string $url): static
         return $this;
     }
 
+    /**
+     * @return $this
+     */
+    public function uploadPhoto(string $path): static
+    {
+        $this->options['upload']['photo'] = $path;
+
+        return $this;
+    }
+
     /**
      * @return $this
      */
@@ -156,4 +166,152 @@ public function answerCallbackQuery(string $callbackQueryId, bool $showAlert = f
 
         return $this;
     }
+
+    /**
+     * @return $this
+     */
+    public function location(float $latitude, float $longitude): static
+    {
+        $this->options['location'] = ['latitude' => $latitude, 'longitude' => $longitude];
+
+        return $this;
+    }
+
+    /**
+     * @return $this
+     */
+    public function venue(float $latitude, float $longitude, string $title, string $address): static
+    {
+        $this->options['venue'] = [
+            'latitude' => $latitude,
+            'longitude' => $longitude,
+            'title' => $title,
+            'address' => $address,
+        ];
+
+        return $this;
+    }
+
+    /**
+     * @return $this
+     */
+    public function document(string $url): static
+    {
+        $this->options['document'] = $url;
+
+        return $this;
+    }
+
+    /**
+     * @return $this
+     */
+    public function uploadDocument(string $path): static
+    {
+        $this->options['upload']['document'] = $path;
+
+        return $this;
+    }
+
+    /**
+     * @return $this
+     */
+    public function video(string $url): static
+    {
+        $this->options['video'] = $url;
+
+        return $this;
+    }
+
+    /**
+     * @return $this
+     */
+    public function uploadVideo(string $path): static
+    {
+        $this->options['upload']['video'] = $path;
+
+        return $this;
+    }
+
+    /**
+     * @return $this
+     */
+    public function audio(string $url): static
+    {
+        $this->options['audio'] = $url;
+
+        return $this;
+    }
+
+    /**
+     * @return $this
+     */
+    public function uploadAudio(string $path): static
+    {
+        $this->options['upload']['audio'] = $path;
+
+        return $this;
+    }
+
+    /**
+     * @return $this
+     */
+    public function animation(string $url): static
+    {
+        $this->options['animation'] = $url;
+
+        return $this;
+    }
+
+    /**
+     * @return $this
+     */
+    public function uploadAnimation(string $path): static
+    {
+        $this->options['upload']['animation'] = $path;
+
+        return $this;
+    }
+
+    /**
+     * @return $this
+     */
+    public function sticker(string $url, string $emoji = null): static
+    {
+        $this->options['sticker'] = $url;
+        $this->options['emoji'] = $emoji;
+
+        return $this;
+    }
+
+    /**
+     * @return $this
+     */
+    public function uploadSticker(string $path, string $emoji = null): static
+    {
+        $this->options['upload']['sticker'] = $path;
+        $this->options['emoji'] = $emoji;
+
+        return $this;
+    }
+
+    /**
+     * @return $this
+     */
+    public function contact(string $phoneNumber, string $firstName, string $lastName = null, string $vCard = null): static
+    {
+        $this->options['contact'] = [
+            'phone_number' => $phoneNumber,
+            'first_name' => $firstName,
+        ];
+
+        if (null !== $lastName) {
+            $this->options['contact']['last_name'] = $lastName;
+        }
+
+        if (null !== $vCard) {
+            $this->options['contact']['vcard'] = $vCard;
+        }
+
+        return $this;
+    }
 }