Merge branch 'main' into payments

# Conflicts:
#	config/telegraph.php
#	docs/12.features/9.dto.md

CHANGELOG.md

@@ -2,6 +2,55 @@
 
 All notable changes to `telegraph` will be documented in this file.
 
+## v1.55.1 - 2024-10-03
+
+### What's Changed
+
+* Added `ReactionType` data type, fixed typing by @andrey-helldar in https://github.com/defstudio/telegraph/pull/652
+
+**Full Changelog**: https://github.com/defstudio/telegraph/compare/v1.55.0...v1.55.1
+
+## v1.55.0 - 2024-10-03
+
+### What's Changed
+
+* Added entities processing by @andrey-helldar in https://github.com/defstudio/telegraph/pull/650
+
+**Full Changelog**: https://github.com/defstudio/telegraph/compare/v1.54.0...v1.55.0
+
+## v1.54.0 - 2024-10-03
+
+### What's Changed
+
+* Added independent methods for saving a chat and forming its name by @andrey-helldar in https://github.com/defstudio/telegraph/pull/647
+* [feat] reactions by @Anze in https://github.com/defstudio/telegraph/pull/641
+* Adding reaction processing when retrieving in webhooks by @andrey-helldar in https://github.com/defstudio/telegraph/pull/649
+* Fix detection of command parameter without passing it by @andrey-helldar in https://github.com/defstudio/telegraph/pull/651
+
+### New Contributors
+
+* @Anze made their first contribution in https://github.com/defstudio/telegraph/pull/641
+
+**Full Changelog**: https://github.com/defstudio/telegraph/compare/v1.53.0...v1.54.0
+
+## v1.53.0 - 2024-09-16
+
+### What's Changed
+
+* #635 implement config for connection request timeout by @MarioGattolla in https://github.com/defstudio/telegraph/pull/636
+* Added the ability to specify different prefixes for command definitions by @andrey-helldar in https://github.com/defstudio/telegraph/pull/643
+* Make protected methods by @andrey-helldar in https://github.com/defstudio/telegraph/pull/642
+
+**Full Changelog**: https://github.com/defstudio/telegraph/compare/v1.52.0...v1.53.0
+
+## v1.52.0 - 2024-08-27
+
+### What's Changed
+
+* [feat] add settings to registerWebhook method by @fabio-ivona and @MarcusLestrange  in https://github.com/defstudio/telegraph/pull/634
+
+**Full Changelog**: https://github.com/defstudio/telegraph/compare/v1.51.0...v1.52.0
+
 ## v1.51.0 - 2024-08-26
 
 ### What's Changed

config/telegraph.php

@@ -60,6 +60,16 @@
          */
         'max_connections' => env('TELEGRAPH_WEBHOOK_MAX_CONNECTIONS', 40),
 
+        /**
+         * List of event types for which the webhook should fire.
+         *
+         * Specify a null to receive all update types except `chat_member`, `message_reaction`,
+         * and `message_reaction_count` (by default).
+         *
+         * @see https://core.telegram.org/bots/api#setwebhook
+         */
+        'allowed_updates' => null,
+
         /*
          * If enabled, Telegraph dumps received
          * webhook messages to logs
@@ -72,6 +82,11 @@
      */
     'http_timeout' => env('TELEGRAPH_HTTP_TIMEOUT', 30),
 
+    /*
+     * Sets HTTP connection request timeout when interacting with Telegram servers
+     */
+    'http_connection_timeout' => env('TELEGRAPH_HTTP_CONNECTION_TIMEOUT', 10),
+
     'security' => [
         /*
          * if enabled, allows callback queries from unregistered chats
@@ -181,6 +196,18 @@
         ],
     ],
 
+    /*
+     * Sets preferences for commands
+     */
+    'commands' => [
+        /*
+         * Defines a list of characters that are the identifier of a command sent to the chat.
+         *
+         * Default is `/`
+         */
+        'start_with' => ['/'],
+    ],
+
     'payments' => [
         'provider_token' => env('TELEGRAPH_PAYMENT_PROVIDER_TOKEN', ''),
     ],

docs/12.features/9.dto.md

@@ -10,6 +10,7 @@ contains incoming data (a message or a callback query)
 
 - `->id()` incoming _update_id_
 - `->message()` (optional) an instance of [`Message`](#message)
+- `->messageReaction()` (optional) an instance of [`Reaction`](#reaction)
 - `->callbackQuery()` (optional) an instance of [`CallbackQuery`](#callback-query)
 
 ## `Chat`
@@ -42,6 +43,7 @@ contains incoming data (a message or a callback query)
 - `->contact()` (optional) an instance of [`Contact`](#contact) holding data about the contained contact data
 - `->voice()` (optional) an instance of [`Voice`](#voice) holding data about the contained voical message
 - `->sticker()` (optional) an instance of [`Sticker`](#sticker) holding data about the contained sticker
+- `->entities()` (optional) a collection of [`Entity`](#entity) holding data about the contained entity
 - `->invoice()` (optional) an instance of [`Invoice`](#invoice) holding data about the contained invoice
 - `->newChatMembers()` a collection of [`User`](#user) holding the list of users that joined the group/supergroup
 - `->leftChatMember()` (optional) an instance of [`User`](#user) holding data about the user that left the group/supergroup
@@ -58,6 +60,22 @@ contains incoming data (a message or a callback query)
 - `->message()` (optional) an instance of the [`Message`](#message) that triggered the callback query
 - `->data()` an `Illuminate\Support\Collection` that holds the key/value pairs of the callback query data
 
+## `Reaction`
+
+- `->id()` incoming _message_id_
+- `->chat()` an instance of [`Chat`](#chat) holding data about the chat to which the message belongs to
+- `->actorChat()` (optional) an instance of [`Chat`](#chat) holding data about the chat to which the chat on behalf of which the reaction was changed, if the user is anonymous
+- `->from()` (optional) an instance of [`User`](#user) holding data about the message's sender
+- `->oldReaction()` a collection of [`ReactionType`](#reactiontype) holding data about the contained reaction type resolutions
+- `->newReaction()` a collection of [`ReactionType`](#reactiontype) holding data about the contained reaction type resolutions
+- `->date()` a `CarbonInterface` holding the message sent 
+
+## `ReactionType`
+
+- `->type()` type of the reaction
+- `->emoji()` reaction emoji
+- `->customEmojiId()` (optional) custom emoji identifier
+
 
 ## `User`
 
@@ -157,6 +175,16 @@ contains incoming data (a message or a callback query)
 - `->filesize()` (optional) sticker file size in Bytes
 - `->thumbnail()` (optional) an instance of the [`Photo`](#photo) that holds data about the thumbnail
 
+## `Entity`
+
+- `->type()` type of the entity
+- `->offset()` offset in UTF-16 code units to the start of the entity
+- `->length()` length of the entity in utf-16 code units
+- `->url()` (optional) for “text_link” only, URL that will be opened after user taps on the text
+- `->user()` (optional) for “text_mention” only, the mentioned [`User`](#user)
+- `->language()` (optional) for “pre” only, the programming language of the entity text
+- `->customEmojiId()` (optional) for “custom_emoji” only, unique identifier of the custom emoji
+
 ## `WriteAccessAllowed`
 
 - `->fromRequest()` true, if the access was granted after the user accepted an explicit request from a Web App sent by the method [requestWriteAccess](https://core.telegram.org/bots/webapps#initializing-mini-apps)

docs/13.api/2.chats.md

@@ -75,7 +75,7 @@ replace a message keyboard (see [keyboards](features/keyboards) for details)
 
 ```php
 Telegraph::replaceKeyboard(
-    $messageId, 
+    $messageId,
     Keyboard::make()->buttons([
         Button::make('open')->url('https://test.dev')
     ])
@@ -98,6 +98,30 @@ sets chat description
 Telegraph::setDescription("a test chat with my bot")->send();
 ```
 
+## `setMessageReaction()`
+
+changes the chosen reactions on a message
+
+```php
+Telegraph::setMessageReaction($messageId, ['type' => 'emoji', 'emoji' => '👍'])->send();
+```
+
+## `reactWithEmoji()`
+
+reaction on a message with emoji
+
+```php
+Telegraph::reactWithEmoji($messageId, '👍')->send();
+```
+
+## `reactWithCustomEmoji()`
+
+reaction on a message with custom emoji
+
+```php
+Telegraph::reactWithCustomEmoji($messageId, '12312')->send();
+```
+
 ## `setChatPhoto()`
 
 sets chat profile photo
@@ -122,9 +146,9 @@ title: my telegram group
 Set menu button. For detailed info, see docs [here](https://core.telegram.org/bots/api#menubutton) and [here](https://core.telegram.org/bots/api#setchatmenubutton)
 
 ```php
-Telegraph::setChatMenuButton()->default()->send(); //restore default 
-Telegraph::setChatMenuButton()->commands()->send(); //show bot commands in menu button 
-Telegraph::setChatMenuButton()->webApp("Web App", "https://my-web.app")->send(); //show start web app button 
+Telegraph::setChatMenuButton()->default()->send(); //restore default
+Telegraph::setChatMenuButton()->commands()->send(); //show bot commands in menu button
+Telegraph::setChatMenuButton()->webApp("Web App", "https://my-web.app")->send(); //show start web app button
 ```
 
 > [!WARNING]

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

@@ -65,7 +65,7 @@ Retrieves the chat member info from telegram
 ```php
 /** @var \DefStudio\Telegraph\Models\TelegraphChat $telegraphChat */
 
-$telegraphChat->memberInfo('user_id'); 
+$telegraphChat->memberInfo('user_id');
 
 /*
 status: string
@@ -177,7 +177,7 @@ Starts a `Telegraph` call to replace a message keyboard (see [keyboards](feature
 /** @var \DefStudio\Telegraph\Models\TelegraphChat $telegraphChat */
 
 $telegraphChat->replaceKeyboard(
-    $messageId, 
+    $messageId,
     Keyboard::make()->buttons([
         Button::make('open')->url('https://test.dev')
     ])
@@ -313,7 +313,41 @@ use DefStudio\Telegraph\Models\TelegraphChat;
 $telegraphChat->setDescription("a test chat with my bot")->send();
 ```
 
+## `setMessageReaction()`
 
+changes the chosen reactions on a message
+
+```php
+use DefStudio\Telegraph\Models\TelegraphChat;
+
+/** @var TelegraphChat $telegraphChat */
+
+$telegraphChat->setMessageReaction($messageId, ['type' => 'emoji', 'emoji' => '👍'])->send();
+```
+
+## `reactWithEmoji()`
+
+reaction on a message with emoji
+
+```php
+use DefStudio\Telegraph\Models\TelegraphChat;
+
+/** @var TelegraphChat $telegraphChat */
+
+$telegraphChat->reactWithEmoji($messageId, '👍')->send();
+```
+
+## `reactWithCustomEmoji()`
+
+reaction on a message with custom emoji
+
+```php
+use DefStudio\Telegraph\Models\TelegraphChat;
+
+/** @var TelegraphChat $telegraphChat */
+
+$telegraphChat->reactWithCustomEmoji($messageId, '12312')->send();
+```
 
 ## `setChatPhoto()`
 
@@ -536,9 +570,9 @@ set chat menu button
 
 ```php
 /** @var DefStudio\Telegraph\Models\TelegraphChat $telegraphChat */
-$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 
+$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
 ```
 
 # `Attachments`

docs/15.webhooks/4.webhook-request-types.md

@@ -4,7 +4,7 @@ navigation.title: 'Request Types'
 ---
 
 
-Telegraph can handle four incoming webhook request types: **Chat Messages**,  **Chat Commands**, **Callback Queries** and **Inline Queries**:
+Telegraph can handle four incoming webhook request types: **Chat Messages**, **Message Reactions**, **Chat Commands**, **Callback Queries** and **Inline Queries**:
 
 ## Chat Messages
 
@@ -46,6 +46,27 @@ class CustomWebhookHandler extends WebhookHandler
 }
 ```
 
+## Message Reactions
+
+Chat messages containing adding and/or deleting user reactions (emojis) to messages.
+
+It can be handled by overriding `DefStudio\Telegraph\Handlers\WebhookHandler::handleChatReaction()` method:
+
+```php
+class CustomWebhookHandler extends WebhookHandler
+{
+    protected function handleChatReaction(array $newReactions, array $oldReactions): void
+    {
+        // in this example, a received emoji message is sent back to the chat
+        $this->chat->html("Received: " . $newReactions[0]['emoji'])->send();
+    }
+}
+```
+
+> [!WARNING]
+> By default, Telegram does not report events related to reactions to messages.
+> To interact with reactions, [specify](config/telegraph.php) in the settings all
+> [types of messages](https://core.telegram.org/bots/api#update) for which you want to catch events.
 
 ## Chat Commands
 

docs/2.installation.md

@@ -89,7 +89,11 @@ return [
      * Sets HTTP request timeout when interacting with Telegram servers
      */
     'http_timeout' => 30,
-
+
+     /*
+     * Sets HTTP connection request timeout when interacting with Telegram servers
+     */
+    'http_connection_timeout' => 10,
 
     'security' => [
         /*

src/Concerns/FakesRequests.php

@@ -10,6 +10,7 @@
 use Illuminate\Foundation\Bus\PendingDispatch;
 use Illuminate\Http\Client\Response;
 use Illuminate\Support\Arr;
+use Illuminate\Support\Collection;
 use Illuminate\Support\Facades\Queue;
 use Illuminate\Support\Str;
 use Illuminate\Support\Testing\Fakes\QueueFake;
@@ -262,9 +263,31 @@ public function dumpSentData(): void
     /** @phpstan-ignore-next-line  */
     public static function assertSentData(string $endpoint, array $data = null, bool $exact = true): void
     {
-        $foundMessages = collect(self::$sentMessages);
+        if ($data == null) {
+            $errorMessage = sprintf("Failed to assert that a request was sent to [%s] endpoint (sent %d requests so far)", $endpoint, count(self::$sentMessages));
+        } else {
+            $errorMessage = sprintf("Failed to assert that a request was sent to [%s] endpoint with the given data (sent %d requests so far)", $endpoint, count(self::$sentMessages));
+        }
+
+        Assert::assertNotEmpty(static::searchMessages($endpoint, $data, $exact)->toArray(), $errorMessage);
+    }
 
-        $foundMessages = $foundMessages
+    /** @phpstan-ignore-next-line  */
+    public static function assertNotSentData(string $endpoint, array $data = null, bool $exact = true): void
+    {
+        if ($data == null) {
+            $errorMessage = sprintf("Failed to assert that a request was sent to [%s] endpoint (sent %d requests so far)", $endpoint, count(self::$sentMessages));
+        } else {
+            $errorMessage = sprintf("Failed to assert that a request was sent to [%s] endpoint with the given data (sent %d requests so far)", $endpoint, count(self::$sentMessages));
+        }
+
+        Assert::assertEmpty(static::searchMessages($endpoint, $data, $exact)->toArray(), $errorMessage);
+    }
+
+    /** @phpstan-ignore-next-line  */
+    protected static function searchMessages(string $endpoint, array $data = null, bool $exact = true): Collection
+    {
+        return collect(self::$sentMessages)
             ->filter(fn (array $message): bool => $message['endpoint'] == $endpoint)
             ->filter(function (array $message) use ($data, $exact): bool {
                 foreach ($data ?? [] as $key => $value) {
@@ -287,14 +310,5 @@ public static function assertSentData(string $endpoint, array $data = null, bool
 
                 return true;
             });
-
-
-        if ($data == null) {
-            $errorMessage = sprintf("Failed to assert that a request was sent to [%s] endpoint (sent %d requests so far)", $endpoint, count(self::$sentMessages));
-        } else {
-            $errorMessage = sprintf("Failed to assert that a request was sent to [%s] endpoint with the given data (sent %d requests so far)", $endpoint, count(self::$sentMessages));
-        }
-
-        Assert::assertNotEmpty($foundMessages->toArray(), $errorMessage);
     }
 }