Merge pull request #616 from YSRoot/implement-forum

Implement forum methods

docs/12.features/7.attachments.md

@@ -19,7 +19,7 @@ Telegraph::withData('caption', 'test')->message('hi')->send();
 Attachments can be sent to a specific Thread through Telegraph `->inThread()` method:
 
 ```php
-Telegraph::message('hi')->inThread('thread_id')->send();
+Telegraph::message('hi')->inThread(THREAD_ID)->send();
 ```
 
 ## Custom validation

docs/12.features/9.dto.md

@@ -23,6 +23,7 @@ contains incoming data (a message or a callback query)
 ## `Message`
 
 - `->id()` incoming _message_id_
+- `->messageThreadId()` unique identifier of a message thread
 - `->date()` a `CarbonInterface` holding the message sent date
 - `->editDate()` a `CarbonInterface` holding the message last edit date
 - `->text()` the message text

docs/13.api/3.messages.md

@@ -173,5 +173,5 @@ Telegraph::quiz("What's your favourite programming language?")
 set custom Telegraph Thread id
 
 ```php
-Telegraph::message('test')->inThread('thread_id');
+Telegraph::message('test')->inThread(thread_id);
 ```

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

@@ -92,7 +92,7 @@ $telegraphChat->withData('caption', 'test')->message('hi')->send();
 Attachments can be sent to a specific Thread through Telegraph `->inThread()` method:
 
 ```php
-$telegraphChat->message('hi')->inThread('thread_id')->send();
+$telegraphChat->message('hi')->inThread(thread_id)->send();
 ```
 
 ### `message()`
@@ -258,22 +258,6 @@ Starts a `Telegraph` call to unpin all messages
 $telegraphChat->unpinAllMessages()->send();
 ```
 
-### `document()`
-
-sends a document
-
-```php
-$telegraphChat->document($documentPath)->send();
-```
-
-### `location()`
-
-sends a location attachment
-
-```php
-$telegraphChat->location(12.345, -54.321)->send();
-````
-
 ### `action()`
 
 Tells the chat users that something is happening on the bot's side. The status is set for up to 5 seconds or when a new message is received from the bot.
@@ -290,32 +274,6 @@ use DefStudio\Telegraph\Models\TelegraphChat;
 $telegraphChat->action(ChatActions::TYPING)->send();
 ```
 
-## `photo()`
-
-sends a photo
-
-```php
-use DefStudio\Telegraph\Models\TelegraphChat;
-
-/** @var TelegraphChat $telegraphChat */
-
-$telegraphChat->photo(Storage::path('photo.jpg'))->send();
-```
-
-
-## `voice()`
-
-sends a vocal message
-
-```php
-use DefStudio\Telegraph\Models\TelegraphChat;
-
-/** @var TelegraphChat $telegraphChat */
-
-$telegraphChat->voice(Storage::path('voice.ogg'))->send();
-```
-
-
 ## `setBaseUrl()`
 
 allows to override Telegram API url on a per-message basis:
@@ -563,8 +521,70 @@ $telegraphChat->poll("What's your favourite programming language?")
     ->validUntil(now()->addMinutes(5))
     ->send();
 ```
+### `menuButton`
+
+Retrieves chat menu button
 
-## `quiz`
+```php
+/** @var DefStudio\Telegraph\Models\TelegraphChat $telegraphChat */
+$button = $telegraphChat->menuButton()->send();
+```
+
+### `setMenuButton`
+
+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 
+```
+
+# `Attachments`
+
+
+### `document()`
+
+sends a document
+
+```php
+$telegraphChat->document($documentPath)->send();
+```
+
+### `location()`
+
+sends a location attachment
+
+```php
+$telegraphChat->location(12.345, -54.321)->send();
+````
+
+### `photo()`
+
+sends a photo
+
+```php
+use DefStudio\Telegraph\Models\TelegraphChat;
+
+/** @var TelegraphChat $telegraphChat */
+
+$telegraphChat->photo(Storage::path('photo.jpg'))->send();
+```
+
+### `voice()`
+
+sends a vocal message
+
+```php
+use DefStudio\Telegraph\Models\TelegraphChat;
+
+/** @var TelegraphChat $telegraphChat */
+
+$telegraphChat->voice(Storage::path('voice.ogg'))->send();
+```
+
+### `quiz`
 
 creates a quiz. For more info, see telegram [bot documentation](https://core.telegram.org/bots/api#sendpoll)
 
@@ -624,40 +644,66 @@ A sticker attachment can be sent through Telegraph `->sticker()` method:
 $telegraphChat->sticker()->send();
 ```
 
+### `media group`
 
-### `menuButton`
+Group of photos, videos, documents or audios as an album can be sent through Telegraph `->mediaGroup()` method:
 
-Retrieves chat menu button
+```php
+$telegraphChat->mediaGroup([
+        [
+            'type' => 'photo',
+            'media' => 'https://my-repository/photo1.jpg',
+        ],
+        [
+            'type' => 'photo',
+            'media' => 'https://my-repository/photo2.jpg',
+        ]              
+])->send();
+```
+
+## `Forum Topic`
+
+### `create topic`
+
+A Forum Topic can be created through Telegraph `->createForumTopic()` method:
 
 ```php
 /** @var DefStudio\Telegraph\Models\TelegraphChat $telegraphChat */
-$button = $telegraphChat->menuButton()->send();
+$telegraphChat->createForumTopic('topic name', 7322096, 'emoji_id')->send();
 ```
 
-### `setMenuButton`
+### `edit topic`
 
-set chat menu button
+A Forum Topic can be edited through Telegraph `->editForumTopic()` method:
 
 ```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->editForumTopic(123456, 'new name', 'emoji_id')->send();
 ```
 
-### `Media Group`
+### `close topic`
 
-Group of photos, videos, documents or audios as an album can be sent through Telegraph `->mediaGroup()` method:
+A Forum Topic can be closed through Telegraph `->closeForumTopic()` method:
 
 ```php
-$telegraphChat->mediaGroup([
-        [
-            'type' => 'photo',
-            'media' => 'https://my-repository/photo1.jpg',
-        ],
-        [
-            'type' => 'photo',
-            'media' => 'https://my-repository/photo2.jpg',
-        ]              
-])->send();
+/** @var DefStudio\Telegraph\Models\TelegraphChat $telegraphChat */
+$telegraphChat->closeForumTopic(123456)->send();
+```
+
+### `reopen topic`
+
+A Forum Topic can be reopened through Telegraph `->reopenForumTopic()` method:
+
+```php
+/** @var DefStudio\Telegraph\Models\TelegraphChat $telegraphChat */
+$telegraphChat->reopenForumTopic(123456)->send();
+```
+
+### `delete topic`
+
+A Forum Topic can be deleted through Telegraph `->deleteForumTopic()` method:
+
+```php
+/** @var DefStudio\Telegraph\Models\TelegraphChat $telegraphChat */
+$telegraphChat->deleteForumTopic(123456)->send();
 ```

src/Concerns/HasBotsAndChats.php

@@ -12,6 +12,7 @@
 use DefStudio\Telegraph\Enums\ChatActions;
 use DefStudio\Telegraph\Enums\ChatAdminPermissions;
 use DefStudio\Telegraph\Exceptions\ChatSettingsException;
+use DefStudio\Telegraph\Exceptions\ChatThreadException;
 use DefStudio\Telegraph\Exceptions\FileException;
 use DefStudio\Telegraph\Exceptions\TelegraphException;
 use DefStudio\Telegraph\Models\TelegraphBot;
@@ -127,6 +128,101 @@ public function leaveChat(): Telegraph
         return $telegraph;
     }
 
+    public function createForumTopic(string $name, int $iconColor = null, string $iconCustomEmojiId = null): Telegraph
+    {
+        $telegraph = clone $this;
+        $telegraph->endpoint = self::ENDPOINT_CREATE_FORUM_TOPIC;
+        $telegraph->data['chat_id'] = $telegraph->getChatId();
+        $telegraph->data['name'] = $name;
+
+        if ($iconColor !== null) {
+            $telegraph->data['icon_color'] = $iconColor;
+        }
+
+        if ($iconCustomEmojiId !== null) {
+            $telegraph->data['icon_custom_emoji_id'] = $iconCustomEmojiId;
+        }
+
+        return $telegraph;
+    }
+
+    public function editForumTopic(int $threadId = null, string $name = null, string $iconCustomEmojiId = null): Telegraph
+    {
+        $telegraph = clone $this;
+
+        if (!isset($telegraph->data['message_thread_id']) && $threadId === null) {
+            throw ChatThreadException::emptyThreadId();
+        }
+
+        $telegraph->endpoint = self::ENDPOINT_EDIT_FORUM_TOPIC;
+        $telegraph->data['chat_id'] = $telegraph->getChatId();
+
+        if ($threadId !== null) {
+            $telegraph->data['message_thread_id'] = $threadId;
+        }
+
+        if ($name !== null) {
+            $telegraph->data['name'] = $name;
+        }
+
+        if ($iconCustomEmojiId !== null) {
+            $telegraph->data['icon_custom_emoji_id'] = $iconCustomEmojiId;
+        }
+
+        return $telegraph;
+    }
+
+    public function closeForumTopic(int $threadId = null): Telegraph
+    {
+        $telegraph = clone $this;
+
+        if (!isset($telegraph->data['message_thread_id']) && $threadId === null) {
+            throw ChatThreadException::emptyThreadId();
+        }
+        $telegraph->endpoint = self::ENDPOINT_CLOSE_FORUM_TOPIC;
+        $telegraph->data['chat_id'] = $telegraph->getChatId();
+
+        if ($threadId !== null) {
+            $telegraph->data['message_thread_id'] = $threadId;
+        }
+
+        return $telegraph;
+    }
+
+    public function reopenForumTopic(int $threadId = null): Telegraph
+    {
+        $telegraph = clone $this;
+
+        if (!isset($telegraph->data['message_thread_id']) && $threadId === null) {
+            throw ChatThreadException::emptyThreadId();
+        }
+        $telegraph->endpoint = self::ENDPOINT_REOPEN_FORUM_TOPIC;
+        $telegraph->data['chat_id'] = $telegraph->getChatId();
+
+        if ($threadId !== null) {
+            $telegraph->data['message_thread_id'] = $threadId;
+        }
+
+        return $telegraph;
+    }
+
+    public function deleteForumTopic(int $threadId = null): Telegraph
+    {
+        $telegraph = clone $this;
+
+        if (!isset($telegraph->data['message_thread_id']) && $threadId === null) {
+            throw ChatThreadException::emptyThreadId();
+        }
+        $telegraph->endpoint = self::ENDPOINT_DELETE_FORUM_TOPIC;
+        $telegraph->data['chat_id'] = $telegraph->getChatId();
+
+        if ($threadId !== null) {
+            $telegraph->data['message_thread_id'] = $threadId;
+        }
+
+        return $telegraph;
+    }
+
     public function botInfo(): Telegraph
     {
         $telegraph = clone $this;