documentation_add_users_activity_handling.patch

Index: docs/content/en/webhooks/dto.md
IDEA additional info:
Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
<+>UTF-8
===================================================================
diff --git a/docs/content/en/webhooks/dto.md b/docs/content/en/webhooks/dto.md
--- a/docs/content/en/webhooks/dto.md	(revision 0d3ad328cda22a16e04ff01167602da437ecda5c)
+++ b/docs/content/en/webhooks/dto.md	(revision 99b12e7b007b194f9ffd8a9783650170599f753c)
@@ -37,6 +37,11 @@
 - `->location()` (optional) an instance of [`DefStudio\Telegraph\DTO\Location`](webhooks/dto#defstudio-telegraph-dto-photo) holding data about the contained location
 - `->contact()` (optional) an instance of [`DefStudio\Telegraph\DTO\Contact`](webhooks/dto#defstudio-telegraph-dto-photo) holding data about the contained contact data
 - `->voice()` (optional) an instance of [`DefStudio\Telegraph\DTO\Voice`](webhooks/dto#defstudio-telegraph-dto-voice) holding data about the contained voical message
+-
+- `->newChatMembers()` a collection of [`DefStudio\Telegraph\DTO\User`](webhooks/dto#defstudio-telegraph-dto-user) holding the list of users that joined the group/supergroup
+- `->leftChatMember()` (optional) an instance of [`DefStudio\Telegraph\DTO\User`](webhooks/dto#defstudio-telegraph-dto-user) holding data about the user that left the group/supergroup
+
+


 ## `DefStudio\Telegraph\DTO\CallbackQuery`
Index: docs/content/en/webhooks/webhook-request-types.md
IDEA additional info:
Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
<+>UTF-8
===================================================================
diff --git a/docs/content/en/webhooks/webhook-request-types.md b/docs/content/en/webhooks/webhook-request-types.md
--- a/docs/content/en/webhooks/webhook-request-types.md	(revision 0d3ad328cda22a16e04ff01167602da437ecda5c)
+++ b/docs/content/en/webhooks/webhook-request-types.md	(revision 99b12e7b007b194f9ffd8a9783650170599f753c)
@@ -10,7 +10,22 @@

 Telegraph can handle two incoming webhook request types: **Chat Messages** and **Callback Queries**

-## Chat Messages
+## Messages
+
+Telegraph bots can receive messages from chats where they are registered and handle them by overriding the `handleChatMessage` method:
+
+```php
+class CustomWebhookHandler extends WebhookHandler
+{
+    protected function handleChatMessage(Stringable $text): void
+    {
+        $this->chat->html("Received this text: $text")->send();
+    }
+}
+```
+
+
+## Chat Commands

 Telegraph bots can receive commands from chats where they are registered. A command is a telegram message has a a `backslash` char followed by a descriptive word, typed in the bot's chat:

@@ -79,6 +94,7 @@
 }
 ```

+
 ## Callback Queries

 Bots messages may ship with keyboard of buttons that trigger actions when pressed:
@@ -166,3 +182,34 @@
 - Venue (coming soon)
 - Video (coming soon)
 - Voice (coming soon)
+
+
+
+
+## Member activities
+
+Telegraph bots can listen for members join/leave activity in chats where they are registered and handle them by overriding `handleChatMemberJoined` and `handleChatMemberLeaved` methods:
+
+### Member joined
+
+```php
+class CustomWebhookHandler extends WebhookHandler
+{
+    protected function handleChatMemberJoined(User $member): void
+    {
+        $this->chat->html("Welcome {$member->firstName()}")->send();
+    }
+}
+```
+
+### Member left
+
+```php
+class CustomWebhookHandler extends WebhookHandler
+{
+    protected function handleChatMemberLeft(User $member): void
+    {
+        $this->chat->html("{$member->firstName()} just left")->send();
+    }
+}
+```
Index: src/DTO/Message.php
IDEA additional info:
Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
<+>UTF-8
===================================================================
diff --git a/src/DTO/Message.php b/src/DTO/Message.php
--- a/src/DTO/Message.php	(revision 0d3ad328cda22a16e04ff01167602da437ecda5c)
+++ b/src/DTO/Message.php	(revision d9fa23d4a3bdd9a60130873dce38c8fb111ab2af)
@@ -30,9 +30,12 @@

     private ?Message $replyToMessage = null;

+    /** @var Collection<array-key, User> */
+    private Collection $newChatMembers;
+    private ?User $leftChatMember = null;
+
     /** @var Collection<array-key, Photo> */
     private Collection $photos;
-
     private ?Audio $audio = null;
     private ?Document $document = null;
     private ?Video $video = null;
@@ -65,6 +68,8 @@
      *     photo?: array<string, mixed>,
      *     location?: array<string, mixed>,
      *     contact?: array<string, mixed>,
+     *     new_chat_members?: array<string, mixed>,
+     *     left_chat_member?: array<string, mixed>,
      *  } $data
      */
     public static function fromArray(array $data): Message
@@ -110,10 +115,8 @@
             $message->keyboard = Keyboard::make();
         }

-        if (isset($data['photo'])) {
-            /* @phpstan-ignore-next-line */
-            $message->photos = collect($data['photo'])->map(fn (array $photoData) => Photo::fromArray($photoData));
-        }
+        /* @phpstan-ignore-next-line */
+        $message->photos = collect($data['photo'] ?? [])->map(fn (array $photoData) => Photo::fromArray($photoData));

         if (isset($data['audio'])) {
             /* @phpstan-ignore-next-line */
@@ -146,6 +149,15 @@
             $message->voice = Voice::fromArray($data['voice']);
         }

+        /* @phpstan-ignore-next-line */
+        $message->newChatMembers = collect($data['new_chat_members'] ?? [])->map(fn (array $userData) => User::fromArray($userData));
+
+
+        if (isset($data['left_chat_member'])) {
+            /* @phpstan-ignore-next-line */
+            $message->leftChatMember = User::fromArray($data['left_chat_member']);
+        }
+
         return $message;
     }

@@ -237,6 +249,19 @@
         return $this->voice;
     }

+    /**
+     * @return Collection<array-key, User>
+     */
+    public function newChatMembers(): Collection
+    {
+        return $this->newChatMembers;
+    }
+
+    public function leftChatMember(): ?User
+    {
+        return $this->leftChatMember;
+    }
+
     public function toArray(): array
     {
         return array_filter([
@@ -257,6 +282,8 @@
             'location' => $this->location?->toArray(),
             'contact' => $this->contact?->toArray(),
             'voice' => $this->voice?->toArray(),
+            'new_chat_members' => $this->newChatMembers->toArray(),
+            'left_chat_member' => $this->leftChatMember,
         ]);
     }
 }
Index: src/Handlers/WebhookHandler.php
IDEA additional info:
Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
<+>UTF-8
===================================================================
diff --git a/src/Handlers/WebhookHandler.php b/src/Handlers/WebhookHandler.php
--- a/src/Handlers/WebhookHandler.php	(revision 0d3ad328cda22a16e04ff01167602da437ecda5c)
+++ b/src/Handlers/WebhookHandler.php	(revision d9fa23d4a3bdd9a60130873dce38c8fb111ab2af)
@@ -12,6 +12,7 @@
 use DefStudio\Telegraph\DTO\Chat;
 use DefStudio\Telegraph\DTO\InlineQuery;
 use DefStudio\Telegraph\DTO\Message;
+use DefStudio\Telegraph\DTO\User;
 use DefStudio\Telegraph\Exceptions\TelegramWebhookException;
 use DefStudio\Telegraph\Keyboard\Keyboard;
 use DefStudio\Telegraph\Models\TelegraphBot;
@@ -105,9 +106,26 @@

         if ($text->startsWith('/')) {
             $this->handleCommand($text);
-        } else {
-            $this->handleChatMessage($text);
-        }
+
+            return;
+        }
+
+
+        if ($this->message?->newChatMembers()->isNotEmpty()) {
+            foreach ($this->message->newChatMembers() as $member) {
+                $this->handleChatMemberJoined($member);
+            }
+
+            return;
+        }
+
+        if ($this->message?->leftChatMember() !== null) {
+            $this->handleChatMemberLeft($this->message->leftChatMember());
+
+            return;
+        }
+
+        $this->handleChatMessage($text);
     }

     protected function canHandle(string $action): bool
@@ -196,6 +214,16 @@
         ]);
     }

+    protected function handleChatMemberJoined(User $member): void
+    {
+        // .. do nothing
+    }
+
+    protected function handleChatMemberLeft(User $member): void
+    {
+        // .. do nothing
+    }
+
     protected function handleChatMessage(Stringable $text): void
     {
         // .. do nothing
Index: tests/Pest.php
IDEA additional info:
Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
<+>UTF-8
===================================================================
diff --git a/tests/Pest.php b/tests/Pest.php
--- a/tests/Pest.php	(revision 0d3ad328cda22a16e04ff01167602da437ecda5c)
+++ b/tests/Pest.php	(revision d9fa23d4a3bdd9a60130873dce38c8fb111ab2af)
@@ -86,6 +86,23 @@
     config()->set('telegraph.webhook_handler', $handler);
 }

+function webhook_message($handler = TestWebhookHandler::class, array $message = null): Request
+{
+    register_webhook_handler($handler);
+
+    return Request::create('', 'POST', [
+        'message' => $message ?? [
+            'message_id' => 123456,
+            'chat' => [
+                'id' => 123456,
+                'type' => 'group',
+                'title' => 'Test chat',
+            ],
+            "text" => 'foo',
+        ],
+    ]);
+}
+
 function webhook_request($action = 'invalid', $handler = TestWebhookHandler::class, int $chat_id = -123456789): Request
 {
     register_webhook_handler($handler);
Index: tests/Support/TestWebhookHandler.php
IDEA additional info:
Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
<+>UTF-8
===================================================================
diff --git a/tests/Support/TestWebhookHandler.php b/tests/Support/TestWebhookHandler.php
--- a/tests/Support/TestWebhookHandler.php	(revision 0d3ad328cda22a16e04ff01167602da437ecda5c)
+++ b/tests/Support/TestWebhookHandler.php	(revision d9fa23d4a3bdd9a60130873dce38c8fb111ab2af)
@@ -8,6 +8,7 @@

 use DefStudio\Telegraph\DTO\InlineQuery;
 use DefStudio\Telegraph\DTO\InlineQueryResultGif;
+use DefStudio\Telegraph\DTO\User;
 use DefStudio\Telegraph\Handlers\WebhookHandler;
 use DefStudio\Telegraph\Keyboard\Button;
 use DefStudio\Telegraph\Keyboard\Keyboard;
@@ -108,4 +109,19 @@

         $this->chat->html("I can't understand your command: $text")->send();
     }
+
+    protected function handleChatMessage(Stringable $text): void
+    {
+        $this->chat->html("Received: $text")->send();
+    }
+
+    protected function handleChatMemberJoined(User $member): void
+    {
+        $this->chat->html("Welcome {$member->firstName()}")->send();
+    }
+
+    protected function handleChatMemberLeft(User $member): void
+    {
+        $this->chat->html("{$member->firstName()} just left")->send();
+    }
 }
Index: tests/Unit/DTO/MessageTest.php
IDEA additional info:
Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
<+>UTF-8
===================================================================
diff --git a/tests/Unit/DTO/MessageTest.php b/tests/Unit/DTO/MessageTest.php
--- a/tests/Unit/DTO/MessageTest.php	(revision 0d3ad328cda22a16e04ff01167602da437ecda5c)
+++ b/tests/Unit/DTO/MessageTest.php	(revision d9fa23d4a3bdd9a60130873dce38c8fb111ab2af)
@@ -198,6 +198,23 @@
             'user_id' => 102030,
             'vcard' => 'fake',
         ],
+        'left_chat_member' => [
+            'id' => 123455,
+            'is_bot' => 'false',
+            'first_name' => 'Steph',
+        ],
+        'new_chat_members' => [
+            [
+                'id' => 123456,
+                'is_bot' => 'false',
+                'first_name' => 'John',
+            ],
+            [
+                'id' => 123457,
+                'is_bot' => 'false',
+                'first_name' => 'Bob',
+            ],
+        ],
     ]);

     $array = $dto->toArray();
Index: tests/Unit/Handlers/WebhookHandlerTest.php
IDEA additional info:
Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
<+>UTF-8
===================================================================
diff --git a/tests/Unit/Handlers/WebhookHandlerTest.php b/tests/Unit/Handlers/WebhookHandlerTest.php
--- a/tests/Unit/Handlers/WebhookHandlerTest.php	(revision 0d3ad328cda22a16e04ff01167602da437ecda5c)
+++ b/tests/Unit/Handlers/WebhookHandlerTest.php	(revision d9fa23d4a3bdd9a60130873dce38c8fb111ab2af)
@@ -273,3 +273,68 @@
         ],
     ]);
 });
+
+it('can handle message', function () {
+    $bot = bot();
+    Facade::fake();
+
+    app(TestWebhookHandler::class)->handle(webhook_message(message: [
+        'message_id' => 123456,
+        'chat' => [
+            'id' => -123456789,
+            'type' => 'group',
+            'title' => 'Test chat',
+        ],
+        'date' => 1646516736,
+        'text' => 'foo',
+    ]), $bot);
+
+    Facade::assertSent("Received: foo");
+});
+
+it('can handle a member join', function () {
+    $bot = bot();
+    Facade::fake();
+
+    app(TestWebhookHandler::class)->handle(webhook_message(message: [
+        'message_id' => 123456,
+        'chat' => [
+            'id' => -123456789,
+            'type' => 'group',
+            'title' => 'Test chat',
+        ],
+        'date' => 1646516736,
+        'new_chat_members' => [
+            [
+                'id' => 123457,
+                'is_bot' => 'false',
+                'first_name' => 'Bob',
+            ],
+        ],
+    ]), $bot);
+
+    Facade::assertSent("Welcome Bob");
+});
+
+
+it('can handle a member left', function () {
+    $bot = bot();
+    Facade::fake();
+
+    app(TestWebhookHandler::class)->handle(webhook_message(message: [
+        'message_id' => 123456,
+        'chat' => [
+            'id' => -123456789,
+            'type' => 'group',
+            'title' => 'Test chat',
+        ],
+        'date' => 1646516736,
+        'left_chat_member' => [
+            'id' => 123457,
+            'is_bot' => 'false',
+            'first_name' => 'Bob',
+        ],
+    ]), $bot);
+
+    Facade::assertSent("Bob just left");
+});