6.0

.gitignore

@@ -1,6 +1,6 @@
 vendor
 build
-.phpunit.result.cache
+.phpunit.cache
 composer.lock
 phpunit.xml
 phpstan.neon

CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to `telegram` will be documented in this file
 
+## 6.0 - (Unreleased)
+
+### What's Changed
+
+* Drop support for Laravel 10.
+* Drop support for PHP 8.1.
+* Add `sendWhen` method to conditionally send a message.
+* Add ParseMode Enum and refactor parsing mode setting logic.
+* Add `buttonWithWebApp` method to open web app from a button.
+* Add `onError` method to handle exceptions. Based of https://github.com/laravel-notification-channels/telegram/pull/201
+* Refactor `escapedLine` method.
+* Refactor `HasSharedLogic` trait.
+* Refactor classes to use PHP 8.2 features.
+* Revise `keyboard` method parameters to `$requestLocation` and `$requestContact` to be consistent.
+
+### New Contributors
+
+* @Hesammousavi made their first contribution in https://github.com/laravel-notification-channels/telegram/pull/201
+
 ## 5.0 - 2024-03-12
 
 ### What's Changed

README.md

@@ -87,10 +87,10 @@ use NotificationChannels\Telegram\TelegramUpdates;
 $updates = TelegramUpdates::create()
     // (Optional). Get's the latest update. NOTE: All previous updates will be forgotten using this method.
     // ->latest()
-    
+
     // (Optional). Limit to 2 updates (By default, updates starting with the earliest unconfirmed update are returned).
     ->limit(2)
-    
+
     // (Optional). Add more params to the request.
     ->options([
         'timeout' => 0,
@@ -154,6 +154,7 @@ class InvoicePaid extends Notification
         return TelegramMessage::create()
             // Optional recipient user id.
             ->to($notifiable->telegram_user_id)
+
             // Markdown supported.
             ->content("Hello there!")
             ->line("Your invoice has been *PAID*")
@@ -165,9 +166,16 @@ class InvoicePaid extends Notification
 
             // (Optional) Inline Buttons
             ->button('View Invoice', $url)
-            ->button('Download Invoice', $url)
+            ->button('Download Invoice', $url);
+
+            // (Optional) Conditional notification. Only send if amount is greater than 0. Otherwise, don't send.
+            // ->sendWhen($notifiable->amount > 0)
+
+            // (Optional) Inline Button with Web App
+            // ->buttonWithWebApp('Open Web App', $url)
+
             // (Optional) Inline Button with callback. You can handle callback in your bot instance
-            ->buttonWithCallback('Confirm', 'confirm_invoice ' . $this->invoice->id);
+            // ->buttonWithCallback('Confirm', 'confirm_invoice ' . $this->invoice->id)
     }
 }
 ```
@@ -362,10 +370,10 @@ Notification::route('telegram', 'TELEGRAM_CHAT_ID')
 
 Using the [notification facade][link-notification-facade] you can send a notification to multiple recipients at once.
 
-> If you're sending bulk notifications to multiple users, the Telegram Bot API will not allow more than 30 messages per second or so. 
+> If you're sending bulk notifications to multiple users, the Telegram Bot API will not allow more than 30 messages per second or so.
 > Consider spreading out notifications over large intervals of 8—12 hours for best results.
 >
-> Also note that your bot will not be able to send more than 20 messages per minute to the same group. 
+> Also note that your bot will not be able to send more than 20 messages per minute to the same group.
 >
 > If you go over the limit, you'll start getting `429` errors. For more details, refer Telegram Bots [FAQ](https://core.telegram.org/bots/faq#broadcasting-to-users).
 
@@ -386,8 +394,11 @@ Notification::send($recipients, new InvoicePaid());
 - `token(string $token)`: Bot token if you wish to override the default token for a specific notification.
 - `button(string $text, string $url, int $columns = 2)`: Adds an inline "Call to Action" button. You can add as many as you want, and they'll be placed 2 in a row by default.
 - `buttonWithCallback(string $text, string $callback_data, int $columns = 2)`: Adds an inline button with the given callback data. You can add as many as you want, and they'll be placed 2 in a row by default.
+- `buttonWithWebApp(string $text, string $url, int $columns = 2)`: Adds an inline button that opens a web application when clicked. This button can be used to direct users to a specific web app.
 - `disableNotification(bool $disableNotification = true)`: Send the message silently. Users will receive a notification with no sound.
 - `options(array $options)`: Allows you to add additional params or override the payload.
+- `sendWhen(bool $condition)`: Sets a condition for sending the notification. If the condition is true, the notification will be sent; otherwise, it will not.
+- `onError(Closure $callback)`: Sets a callback function to handle exceptions. Callback receives an array with `to`, `request`, `exception` keys.
 - `getPayloadValue(string $key)`: Get payload value for given key.
 
 ### Telegram Message methods

composer.json

@@ -19,23 +19,23 @@
     ],
     "homepage": "https://github.com/laravel-notification-channels/telegram",
     "require": {
-        "php": "^8.1",
+        "php": "^8.2",
         "ext-json": "*",
-        "guzzlehttp/guzzle": "^7.2",
-        "illuminate/contracts": "^10 || ^11.0",
-        "illuminate/notifications": "^10 || ^11.0",
-        "illuminate/support": "^10 || ^11.0"
+        "guzzlehttp/guzzle": "^7.8",
+        "illuminate/contracts": "^11.0",
+        "illuminate/notifications": "^11.0",
+        "illuminate/support": "^11.0"
     },
     "require-dev": {
         "larastan/larastan": "^2.9",
         "mockery/mockery": "^1.4.4",
         "orchestra/testbench": "^8.0 || ^9.0",
-        "pestphp/pest": "^2.34",
-        "pestphp/pest-plugin-laravel": "^2.3",
+        "pestphp/pest": "^3.0",
+        "pestphp/pest-plugin-laravel": "^3.0",
         "phpstan/extension-installer": "^1.2",
         "phpstan/phpstan-deprecation-rules": "^1.1",
         "phpstan/phpstan-phpunit": "^1.3",
-        "phpunit/phpunit": "^10.5 || ^11.0"
+        "phpunit/phpunit": "^11.0"
     },
     "minimum-stability": "dev",
     "prefer-stable": true,

phpstan.neon.dist

@@ -6,4 +6,3 @@ parameters:
   paths:
     - src
   tmpDir: build/phpstan
-  checkMissingIterableValueType: false

src/Enums/ParseMode.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace NotificationChannels\Telegram\Enums;
+
+enum ParseMode: string
+{
+    case Markdown = 'Markdown';
+    case HTML = 'HTML';
+    case MarkdownV2 = 'MarkdownV2';
+}

src/Telegram.php

@@ -15,19 +15,22 @@
 class Telegram
 {
     /** @var HttpClient HTTP Client */
-    protected HttpClient $http;
+    protected readonly HttpClient $http;
 
     /** @var null|string Telegram Bot API Token. */
     protected ?string $token;
 
     /** @var string Telegram Bot API Base URI */
     protected string $apiBaseUri;
 
-    public function __construct(?string $token = null, ?HttpClient $httpClient = null, ?string $apiBaseUri = null)
-    {
+    public function __construct(
+        ?string $token = null,
+        HttpClient $httpClient = new HttpClient(),
+        string $apiBaseUri = 'https://api.telegram.org'
+    ) {
         $this->token = $token;
-        $this->http = $httpClient ?? new HttpClient();
-        $this->setApiBaseUri($apiBaseUri ?? 'https://api.telegram.org');
+        $this->http = $httpClient;
+        $this->setApiBaseUri($apiBaseUri);
     }
 
     /**
@@ -112,9 +115,9 @@ public function sendMessage(array $params): ?ResponseInterface
      *
      * @throws CouldNotSendNotification
      */
-    public function sendFile(array $params, string $type, bool $multipart = false): ?ResponseInterface
+    public function sendFile(array $params, string|array $type, bool $multipart = false): ?ResponseInterface
     {
-        return $this->sendRequest('send'.Str::studly($type), $params, $multipart);
+        return $this->sendRequest('send'.Str::studly((array)$type[0]), $params, $multipart);
     }
 
     /**

src/TelegramChannel.php

@@ -13,15 +13,9 @@
  */
 class TelegramChannel
 {
-    private Dispatcher $dispatcher;
-
-    /**
-     * Channel constructor.
-     */
-    public function __construct(Dispatcher $dispatcher)
-    {
-        $this->dispatcher = $dispatcher;
-    }
+    public function __construct(
+        private readonly Dispatcher $dispatcher
+    ) {}
 
     /**
      * Send the given notification.
@@ -38,33 +32,44 @@ public function send(mixed $notifiable, Notification $notification): ?array
             $message = TelegramMessage::create($message);
         }
 
-        if ($message->toNotGiven()) {
-            $to = $notifiable->routeNotificationFor('telegram', $notification)
-                ?? $notifiable->routeNotificationFor(self::class, $notification);
+        if (!$message->canSend()) {
+            return null;
+        }
 
-            if (! $to) {
-                return null;
-            }
+        $to = $message->getPayloadValue('chat_id') ?:
+              ($notifiable->routeNotificationFor('telegram', $notification) ?:
+              $notifiable->routeNotificationFor(self::class, $notification));
 
-            $message->to($to);
+        if (! $to) {
+            return null;
         }
 
+        $message->to($to);
+
         if ($message->hasToken()) {
             $message->telegram->setToken($message->token);
         }
 
         try {
             $response = $message->send();
         } catch (CouldNotSendNotification $exception) {
-            $this->dispatcher->dispatch(new NotificationFailed($notifiable, $notification, 'telegram', [
+            $data = [
                 'to' => $message->getPayloadValue('chat_id'),
                 'request' => $message->toArray(),
                 'exception' => $exception,
-            ]));
+            ];
+
+            if ($message->exceptionHandler) {
+                ($message->exceptionHandler)($data);
+            }
+
+            $this->dispatcher->dispatch(new NotificationFailed($notifiable, $notification, 'telegram', $data));
 
             throw $exception;
         }
 
-        return $response instanceof Response ? json_decode($response->getBody()->getContents(), true, 512, JSON_THROW_ON_ERROR) : $response;
+        return $response instanceof Response
+                ? json_decode($response->getBody()->getContents(), true, 512, JSON_THROW_ON_ERROR)
+                : $response;
     }
 }