From f26de7994fcb96f0a5d914509dd49d458f0bb8bc Mon Sep 17 00:00:00 2001 From: Fabio Ivona Date: Tue, 16 Jul 2024 18:29:37 +0200 Subject: [PATCH] docs optimization --- docs/12.features/8.telegram-api-calls.md | 600 ------------------ docs/13.api/1.bots.md | 135 ++++ docs/13.api/2.chats.md | 273 ++++++++ docs/13.api/3.messages.md | 177 ++++++ docs/13.api/4.webhooks.md | 29 + docs/13.api/5.helpers.md | 30 + .../1.telegraph-bot.md | 0 .../2.telegraph-chat.md | 0 .../1.overview.md | 0 .../2.registering-webhooks.md | 0 .../3.deleting-webhooks.md | 0 .../4.webhook-request-types.md | 0 .../5.callback-data.md | 0 .../6.callback-reply.md | 0 .../7.keyboard-interaction.md | 0 .../8.manual-polling.md | 0 .../1.entities_storage.md | 0 docs/{16.testing => 17.testing}/1.fake.md | 0 .../2.assertions.md | 0 .../1.contributing.md | 0 .../2.translating.md | 0 .../3.releases.md | 0 .../4.changelog.md | 0 23 files changed, 644 insertions(+), 600 deletions(-) delete mode 100644 docs/12.features/8.telegram-api-calls.md create mode 100644 docs/13.api/1.bots.md create mode 100644 docs/13.api/2.chats.md create mode 100644 docs/13.api/3.messages.md create mode 100644 docs/13.api/4.webhooks.md create mode 100644 docs/13.api/5.helpers.md rename docs/{13.models => 14.models}/1.telegraph-bot.md (100%) rename docs/{13.models => 14.models}/2.telegraph-chat.md (100%) rename docs/{14.webhooks => 15.webhooks}/1.overview.md (100%) rename docs/{14.webhooks => 15.webhooks}/2.registering-webhooks.md (100%) rename docs/{14.webhooks => 15.webhooks}/3.deleting-webhooks.md (100%) rename docs/{14.webhooks => 15.webhooks}/4.webhook-request-types.md (100%) rename docs/{14.webhooks => 15.webhooks}/5.callback-data.md (100%) rename docs/{14.webhooks => 15.webhooks}/6.callback-reply.md (100%) rename docs/{14.webhooks => 15.webhooks}/7.keyboard-interaction.md (100%) rename docs/{14.webhooks => 15.webhooks}/8.manual-polling.md (100%) rename docs/{15.storage => 16.storage}/1.entities_storage.md (100%) rename docs/{16.testing => 17.testing}/1.fake.md (100%) rename docs/{16.testing => 17.testing}/2.assertions.md (100%) rename docs/{17.community => 18.community}/1.contributing.md (100%) rename docs/{17.community => 18.community}/2.translating.md (100%) rename docs/{17.community => 18.community}/3.releases.md (100%) rename docs/{17.community => 18.community}/4.changelog.md (100%) diff --git a/docs/12.features/8.telegram-api-calls.md b/docs/12.features/8.telegram-api-calls.md deleted file mode 100644 index 3f8feb21b..000000000 --- a/docs/12.features/8.telegram-api-calls.md +++ /dev/null @@ -1,600 +0,0 @@ ---- -title: 'Telegram API calls' -navigation.title: 'Telegram API calls' ---- - -## answerInlineQuery - -send back the results for an inline query - -```php - Telegraph::answerInlineQuery($inlineQuery->id(), [ - InlineQueryResultPhoto::make($logo->id."-light", "https://logofinder.dev/$logo->id/light.jpg", "https://logofinder.dev/$logo->id/light/thumb.jpg") - ->caption('Light Logo'), - InlineQueryResultPhoto::make($logo->id."-dark", "https://logofinder.dev/$logo->id/dark.jpg", "https://logofinder.dev/$logo->id/dark/thumb.jpg") - ->caption('Dark Logo'), -])->cache(seconds: 600)->send(); -``` - -## botInfo - -retrieves Bot data from Telegram APIs - -```php -Telegraph::botInfo()->send(); - -/* -id: xxxxx -is_bot: true -first_name: telegraph-test -username: my_test_bot -can_join_groups: true -can_read_all_group_messages: false -supports_inline_queries: false -*/ -``` - -## botUpdates - -retrieves the bot updates from Telegram APIs - -```php -Telegraph::bot($telegraphBot)->botUpdates()->send(); -``` - -> [!WARNING] -> Manual updates polling is not available if a webhook is set up for the bot. Webhook should be remove first using its [unregisterWebhook](webhooks/deleting-webhooks) method - -### Long Polling - -In production environment, a timeout (in seconds) should be declared, in order to allow long polling: - -```php -Telegraph::bot($telegraphBot)->botUpdates(timeout: 60)->send(); -``` - - -## chatAction - -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. - - - -```php -Telegraph::chatAction(ChatActions::TYPING)->send(); -``` - -## deleteMessage - -deletes a message - -```php -Telegraph::deleteMessage($messageId)->send(); -``` - -## deleteMessages - -deletes multiple messages - -```php -Telegraph::deleteMessages(array $messageIds)->send(); -``` - -## forwardMessage - -forwards a message from another chat - -```php -Telegraph::forwardMessage($fromChat, $messageId)->send(); -``` - -## pinMessage - -pins a message - -```php -Telegraph::pinMessage($messageId)->send(); -``` - -## unpinMessage - -unpins a message - -```php -Telegraph::unpinMessage($messageId)->send(); -``` - -## unpinAllMessages - -unpin al messages - -```php -Telegraph::unpinAllMessages()->send(); -``` - -## deleteKeyboard - -removes a message keyboard (see [keyboards](features/keyboards) for details) - -```php -Telegraph::deleteKeyboard($messageId)->send(); -``` - -## document - -sends a document - -```php -Telegraph::document($documentPath)->send(); -``` - -## edit - -edits a message - -```php -Telegraph::edit($messageId)->markdown('new message')->send(); -``` - -## editCaption - -edits an attachment caption - -```php -Telegraph::editCaption($messageId)->markdownV2('new caption')->send(); -``` - -## editMedia - -edits a media messages with a new media content - -```php -Telegraph::editMedia($messageId)->photo($path)->send(); -Telegraph::editMedia($messageId)->document($path)->send(); -Telegraph::editMedia($messageId)->animation($path)->send(); -Telegraph::editMedia($messageId)->video($path)->send(); -Telegraph::editMedia($messageId)->audio($path)->send(); -``` - -## getWebhookDebugInfo - -retrieves webhook debug data for the active bot - -```php -$response = Telegraph::getWebhookDebugInfo()->send(); -``` - -## location - -sends a location attachment - -```php -Telegraph::location(12.345, -54.321)->send(); -``` - -## contact - -sens a contact attachment - -```php -Telegraph::contact('3331122111', 'firstName')->send(); -``` - -## markdown - -compose a new telegram message (parsed as markdown) - -```php -Telegraph::markdown('*hello* world')->send(); -``` - -## markdownV2 - -compose a new telegram message (parsed as markdownV2) - -```php -Telegraph::markdownV2('*hello* world')->send(); -``` - -## message - -compose a new telegram message (will use the default parse mode set up in `config/telegraph.php`) - -```php -Telegraph::message('hello')->send(); -``` - -## html - -compose a new telegram message (parsed as html) - -```php -Telegraph::html('hello world')->send(); -``` - -## photo - -sends a photo - -```php -Telegraph::photo($pathToPhotoFile)->send(); -``` - -## mediaGroup - -sends a group of photos, videos, documents or audios as an album - -```php -Telegraph::mediaGroup([ - [ - 'type' => 'photo', - 'media' => 'https://my-repository/photo1.jpg', - ], - [ - 'type' => 'photo', - 'media' => 'https://my-repository/photo2.jpg', - ] -])->send(); -``` - -## registerBotCommands - -register commands in Telegram Bot in order to display them to the user when the "/" key is pressed - -```php -Telegraph::registerBotCommands([ - 'command1' => 'command 1 description', - 'command2' => 'command 2 description' -])->send(); -``` - -## getRegisteredCommands - -retrieve bot's registered commands. - -```php -$response = Telegraph::getRegisteredCommands()->send(); -$response->json('result'); -``` - -## registerWebhook - -register a webhook for the active bot - -```php -Telegraph::registerWebhook()->send(); -``` - -## replaceKeyboard - -replace a message keyboard (see [keyboards](features/keyboards) for details) - -```php -Telegraph::replaceKeyboard( - $messageId, - Keyboard::make()->buttons([ - Button::make('open')->url('https://test.dev') - ]) -)->send(); -``` - -## replyWebhook - -replies to a webhook callback - -```php -Telegraph::replyWebhook($callbackQueryId, 'message received', $showAlert)->send(); -``` - -## store - -Downloads a media file and stores it in the given path - -```php -/** @var DefStudio\Telegraph\DTO\Photo $photo */ - -Telegraph::store($photo, Storage::path('bot/images'), 'The Photo.jpg'); -``` - -> [!WARNING] -> There is an hard limit of 20BM for downloaded files sizes. This is a Telegram limitation for bots, sadly, there is no workaround available. -> refer the [docs](https://core.telegram.org/bots/api#getfile) for more info. - -## unregisterBotCommands - -resets Telegram Bot registered commands - -```php -Telegraph::unregisterBotCommands()->send(); -``` - -## unregisterWebhook - -unregister a webhook for the active bot - -```php -Telegraph::registerWebhook()->send(); -``` - -## voice - -sends a vocal message - -```php -Telegraph::voice($pathToVoiceFile)->send(); -``` - -## when - -allows to execute a closure when the given condition is verified - -```php -Telegraph::when(true, fn(Telegraph $telegraph) => $telegraph->message('conditional message')->send()); -``` - -## setBaseUrl - -allows to override Telegram API url on a per-message basis: - -```php -Telegraph::setBaseUrl('https://my-secret-server.dev')->message('secret message')->send(); -``` - -## setTitle - -sets chat title - -```php -Telegraph::setTitle("my chat")->send(); -``` - -## setDescription - -sets chat description - -```php -Telegraph::setDescription("a test chat with my bot")->send(); -``` - -## setChatPhoto - -sets chat profile photo - -## chatInfo - -retrieves Chat data from Telegram APIs - -```php -Telegraph::chatInfo()->send(); - -/* -id: xxxxx -type: group -title: my telegram group -... -*/ -``` - -## setChatMenuButton - -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 -``` - -> [!WARNING] -> if no chat is active when calling this, the default bot's menu button will be changed. - -## chatMenuButton - -retrieves a bot current menu button info - -```php -Telegraph::chatMenuButton()->send(); -``` - -## getFileInfo - -Retrieve file info from ID - -```php -Telegraph::getFileInfo($fileId)->send(); -``` - -## chatMemberCount - -retrieves Chat member count - -```php -Telegraph::chatMemberCount()->send(); -``` - -## chatMember - -retrieves a Chat member - -```php -Telegraph::chatMember($userId)->send(); -``` - -## userProfilePhotos - -retrieves the User's profile photos - -```php -Telegraph::userProfilePhotos($userId)->send(); -``` - -## generateChatPrimaryInviteLink - -generates a new primary invite link for a chat. Any previously generated primary link is revoked. For more info, see telegram [bot documentation](https://core.telegram.org/bots/api#exportchatinvitelink) - -```php -Telegraph::generateChatPrimaryInviteLink()->send(); -``` - -## createChatInviteLink - -creates an additional invite link for a chat. For more info about options, see telegram [bot documentation](https://core.telegram.org/bots/api#createchatinvitelink) - -```php -Telegraph::createChatInviteLink() - ->name('September promotional link') //optional - ->expire(today()->addMonth()) //optional - ->memberLimit(42) //optional - ->withJoinRequest() //optional - ->send(); -``` - -## editChatInviteLink - -edits an existing invite link for a chat. For more info about options, see telegram [bot documentation](https://core.telegram.org/bots/api#editchatinvitelink) - -```php -Telegraph::editChatInviteLink('http://t.me/123456') - ->name('new name') //optional - ->expire(today()->addYear()) //optional - ->memberLimit(12) //optional - ->withJoinRequest(false) //optional - ->send(); -``` - -## revokeChatInviteLink - -revokes an existing invite link for a chat. For more info, see telegram [bot documentation](https://core.telegram.org/bots/api#revokechatinvitelink) - -```php -Telegraph::revokeChatInviteLink('http://t.me/123456')->send(); -``` - -## setChatPermissions - -set users permissions for a chat. For more info, see telegram [bot documentation](https://core.telegram.org/bots/api#setchatpermissions) - -```php -Telegraph::setChatPermissions([ - ChatPermissions::CAN_INVITE_USERS, - ChatPermissions::CAN_CHANGE_INFO, - ChatPermissions::CAN_ADD_WEB_PAGE_PREVIEWS => true, - ChatPermissions::CAN_SEND_MESSAGES => false, -])->send(); -``` - -## banChatMember - -ban a user in a group, a supergroup or a channel. In the case of supergroups and channels, the user will not be able to return to the chat on their own using invite links. For more info, see telegram [bot documentation](https://core.telegram.org/bots/api#banchatmember) - -```php -Telegraph::banChatMember($userid) - ->until(now()->addDay()); //optional, only for supergroups and channels - ->andRevokeMessages() //optional, always true for supergroups and channels - ->send(); -``` - -## unbanChatMember - -unban a user in a group, a supergroup or a channel. For more info, see telegram [bot documentation](https://core.telegram.org/bots/api#unbanchatmember) - -```php -Telegraph::unbanChatMember($userid)->send(); -``` - -## restrictChatMember - -restrict a user in a group, a supergroup or a channel from taking the give actions. For more info, see telegram [bot documentation](https://core.telegram.org/bots/api#restrictchatmember) - -```php -Telegraph::restrictChatMember($userid, [ - DefStudio\Telegraph\Enums\ChatPermissions::CAN_PIN_MESSAGES => false, - DefStudio\Telegraph\Enums\ChatPermissions::CAN_INVITE_USERS => true, - DefStudio\Telegraph\Enums\ChatPermissions::CAN_SEND_MESSAGES, - ]) - ->until(now()->addDay()) //optional - ->send(); -``` - -## promoteChatMember - -promotes a user in a group, a supergroup or a channel to administrator status. For more info, see telegram [bot documentation](https://core.telegram.org/bots/api#promotechatmember) - -```php -Telegraph::promoteChatMember($userid, [ - DefStudio\Telegraph\Enums\ChatAdminPermissions::CAN_PIN_MESSAGES => false, - DefStudio\Telegraph\Enums\ChatAdminPermissions::CAN_INVITE_USERS => true, - DefStudio\Telegraph\Enums\ChatAdminPermissions::CAN_CHANGE_INFO, -]) -->send(); -``` - -## demoteChatMember - -demote a user in a group, a supergroup or a channel from administrator status. - -```php -Telegraph::demoteChatMember($userid)->send(); -``` - -## poll - -creates a native poll. For more info, see telegram [bot documentation](https://core.telegram.org/bots/api#sendpoll) - -```php -Telegraph::poll("What's your favourite programming language?") - ->option('php') - ->option('typescript') - ->option('rust') - ->allowMultipeAnswers() - ->validUntil(now()->addMinutes(5)) - ->send(); -``` - -## quiz - -creates a quiz. For more info, see telegram [bot documentation](https://core.telegram.org/bots/api#sendpoll) - -```php -Telegraph::quiz("What's your favourite programming language?") - ->option('php', correct: true) - ->option('typescript') - ->option('rust') - ->explanation('We all love php, right?') - ->validUntil(now()->addMinutes(5)) - ->send(); -``` - -## dump - -print a `dump()` of the current api call status for testing purposes - -```php -Telegraph::message('test')->dump(); -``` - -## dd - -print a `dd()` of the current api call status for testing purposes - -```php -Telegraph::message('test')->dd(); -``` - - -## withData - -set custom Telegraph data attribute - -```php -Telegraph::withData('key', 'value'); -``` - -## thread - -set custom Telegraph Thread id - -```php -Telegraph::message('test')->inThread('thread_id'); -``` - diff --git a/docs/13.api/1.bots.md b/docs/13.api/1.bots.md new file mode 100644 index 000000000..efc4e85ca --- /dev/null +++ b/docs/13.api/1.bots.md @@ -0,0 +1,135 @@ +--- +title: 'Bots API calls' +navigation.title: 'Bot Management' +--- + +## `botInfo()` + +retrieves Bot data from Telegram APIs + +```php +Telegraph::botInfo()->send(); + +/* +id: xxxxx +is_bot: true +first_name: telegraph-test +username: my_test_bot +can_join_groups: true +can_read_all_group_messages: false +supports_inline_queries: false +*/ +``` + + +## `botUpdates()` + +retrieves the bot updates from Telegram APIs + +```php +Telegraph::bot($telegraphBot)->botUpdates()->send(); +``` + +> [!WARNING] +> Manual updates polling is not available if a webhook is set up for the bot. Webhook should be remove first using its [unregisterWebhook](webhooks/deleting-webhooks) method + + +### `Long Polling` + +In production environment, a timeout (in seconds) should be declared, in order to allow long polling: + +```php +Telegraph::bot($telegraphBot)->botUpdates(timeout: 60)->send(); +``` + + + +## `registerBotCommands()` + +register commands in Telegram Bot in order to display them to the user when the "/" key is pressed + +```php +Telegraph::registerBotCommands([ + 'command1' => 'command 1 description', + 'command2' => 'command 2 description' +])->send(); +``` + +## `unregisterBotCommands()` + +resets Telegram Bot registered commands + +```php +Telegraph::unregisterBotCommands()->send(); +``` + +## `getRegisteredCommands()` + +retrieve bot's registered commands. + +```php +$response = Telegraph::getRegisteredCommands()->send(); +$response->json('result'); +``` + + + +## `registerWebhook()` + +register a webhook for the active bot + +```php +Telegraph::registerWebhook()->send(); +``` + +## `unregisterWebhook()` + +unregister a webhook for the active bot + +```php +Telegraph::registerWebhook()->send(); +``` + + +## `getWebhookDebugInfo()` + +retrieves webhook debug data for the active bot + +```php +$response = Telegraph::getWebhookDebugInfo()->send(); +``` + + +## `getFileInfo` + +Retrieve file info from ID + +```php +Telegraph::getFileInfo($fileId)->send(); +``` + + + + +## `store()` + +Downloads a media file and stores it in the given path + +```php +/** @var DefStudio\Telegraph\DTO\Photo $photo */ + +Telegraph::store($photo, Storage::path('bot/images'), 'The Photo.jpg'); +``` + +> [!WARNING] +> There is an hard limit of 20BM for downloaded files sizes. This is a Telegram limitation for bots, sadly, there is no workaround available. +> refer the [docs](https://core.telegram.org/bots/api#getfile) for more info. + + +## `setBaseUrl()` + +allows to override Telegram API url on a per-message basis: + +```php +Telegraph::setBaseUrl('https://my-secret-server.dev')->message('secret message')->send(); +``` diff --git a/docs/13.api/2.chats.md b/docs/13.api/2.chats.md new file mode 100644 index 000000000..65722dea0 --- /dev/null +++ b/docs/13.api/2.chats.md @@ -0,0 +1,273 @@ +--- +title: 'Chat API calls' +navigation.title: 'Chat Management' +--- + +## `chatAction()` + +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. + + + +```php +Telegraph::chatAction(ChatActions::TYPING)->send(); +``` + +## `deleteMessage()` + +deletes a message + +```php +Telegraph::deleteMessage($messageId)->send(); +``` + +## `deleteMessages()` + +deletes multiple messages + +```php +Telegraph::deleteMessages(array $messageIds)->send(); +``` + +## `forwardMessage()` + +forwards a message from another chat + +```php +Telegraph::forwardMessage($fromChat, $messageId)->send(); +``` + +## `pinMessage()` + +pins a message + +```php +Telegraph::pinMessage($messageId)->send(); +``` + +## `unpinMessage()` + +unpins a message + +```php +Telegraph::unpinMessage($messageId)->send(); +``` + +## `unpinAllMessages()` + +unpin al messages + +```php +Telegraph::unpinAllMessages()->send(); +``` + +## `deleteKeyboard()` + +removes a message keyboard (see [keyboards](features/keyboards) for details) + +```php +Telegraph::deleteKeyboard($messageId)->send(); +``` + +## `replaceKeyboard()` + +replace a message keyboard (see [keyboards](features/keyboards) for details) + +```php +Telegraph::replaceKeyboard( + $messageId, + Keyboard::make()->buttons([ + Button::make('open')->url('https://test.dev') + ]) +)->send(); +``` + +## `setTitle()` + +sets chat title + +```php +Telegraph::setTitle("my chat")->send(); +``` + +## `setDescription()` + +sets chat description + +```php +Telegraph::setDescription("a test chat with my bot")->send(); +``` + +## `setChatPhoto()` + +sets chat profile photo + +## `chatInfo()` + +retrieves Chat data from Telegram APIs + +```php +Telegraph::chatInfo()->send(); + +/* +id: xxxxx +type: group +title: my telegram group +... +*/ +``` + +## `setChatMenuButton()` + +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 +``` + +> [!WARNING] +> if no chat is active when calling this, the default bot's menu button will be changed. + +## `chatMenuButton()` + +retrieves a bot current menu button info + +```php +Telegraph::chatMenuButton()->send(); +``` + + +## `chatMemberCount()` + +retrieves Chat member count + +```php +Telegraph::chatMemberCount()->send(); +``` + +## `chatMember()` + +retrieves a Chat member + +```php +Telegraph::chatMember($userId)->send(); +``` + +## `userProfilePhotos()` + +retrieves the User's profile photos + +```php +Telegraph::userProfilePhotos($userId)->send(); +``` + +## `generateChatPrimaryInviteLink()` + +generates a new primary invite link for a chat. Any previously generated primary link is revoked. For more info, see telegram [bot documentation](https://core.telegram.org/bots/api#exportchatinvitelink) + +```php +Telegraph::generateChatPrimaryInviteLink()->send(); +``` + +## `createChatInviteLink()` + +creates an additional invite link for a chat. For more info about options, see telegram [bot documentation](https://core.telegram.org/bots/api#createchatinvitelink) + +```php +Telegraph::createChatInviteLink() + ->name('September promotional link') //optional + ->expire(today()->addMonth()) //optional + ->memberLimit(42) //optional + ->withJoinRequest() //optional + ->send(); +``` + +## `editChatInviteLink()` + +edits an existing invite link for a chat. For more info about options, see telegram [bot documentation](https://core.telegram.org/bots/api#editchatinvitelink) + +```php +Telegraph::editChatInviteLink('http://t.me/123456') + ->name('new name') //optional + ->expire(today()->addYear()) //optional + ->memberLimit(12) //optional + ->withJoinRequest(false) //optional + ->send(); +``` + +## `revokeChatInviteLink()` + +revokes an existing invite link for a chat. For more info, see telegram [bot documentation](https://core.telegram.org/bots/api#revokechatinvitelink) + +```php +Telegraph::revokeChatInviteLink('http://t.me/123456')->send(); +``` + +## `setChatPermissions()` + +set users permissions for a chat. For more info, see telegram [bot documentation](https://core.telegram.org/bots/api#setchatpermissions) + +```php +Telegraph::setChatPermissions([ + ChatPermissions::CAN_INVITE_USERS, + ChatPermissions::CAN_CHANGE_INFO, + ChatPermissions::CAN_ADD_WEB_PAGE_PREVIEWS => true, + ChatPermissions::CAN_SEND_MESSAGES => false, +])->send(); +``` + +## `banChatMember()` + +ban a user in a group, a supergroup or a channel. In the case of supergroups and channels, the user will not be able to return to the chat on their own using invite links. For more info, see telegram [bot documentation](https://core.telegram.org/bots/api#banchatmember) + +```php +Telegraph::banChatMember($userid) + ->until(now()->addDay()); //optional, only for supergroups and channels + ->andRevokeMessages() //optional, always true for supergroups and channels + ->send(); +``` + +## `unbanChatMember()` + +unban a user in a group, a supergroup or a channel. For more info, see telegram [bot documentation](https://core.telegram.org/bots/api#unbanchatmember) + +```php +Telegraph::unbanChatMember($userid)->send(); +``` + +## `restrictChatMember()` + +restrict a user in a group, a supergroup or a channel from taking the give actions. For more info, see telegram [bot documentation](https://core.telegram.org/bots/api#restrictchatmember) + +```php +Telegraph::restrictChatMember($userid, [ + DefStudio\Telegraph\Enums\ChatPermissions::CAN_PIN_MESSAGES => false, + DefStudio\Telegraph\Enums\ChatPermissions::CAN_INVITE_USERS => true, + DefStudio\Telegraph\Enums\ChatPermissions::CAN_SEND_MESSAGES, + ]) + ->until(now()->addDay()) //optional + ->send(); +``` + +## `promoteChatMember()` + +promotes a user in a group, a supergroup or a channel to administrator status. For more info, see telegram [bot documentation](https://core.telegram.org/bots/api#promotechatmember) + +```php +Telegraph::promoteChatMember($userid, [ + DefStudio\Telegraph\Enums\ChatAdminPermissions::CAN_PIN_MESSAGES => false, + DefStudio\Telegraph\Enums\ChatAdminPermissions::CAN_INVITE_USERS => true, + DefStudio\Telegraph\Enums\ChatAdminPermissions::CAN_CHANGE_INFO, +]) +->send(); +``` + +## `demoteChatMember()` + +demote a user in a group, a supergroup or a channel from administrator status. + +```php +Telegraph::demoteChatMember($userid)->send(); +``` diff --git a/docs/13.api/3.messages.md b/docs/13.api/3.messages.md new file mode 100644 index 000000000..8f449d40d --- /dev/null +++ b/docs/13.api/3.messages.md @@ -0,0 +1,177 @@ +--- +title: 'Message API calls' +navigation.title: 'Messages' +--- + + +## `message()` + +compose a new telegram message (will use the default parse mode set up in `config/telegraph.php`) + +```php +Telegraph::message('hello')->send(); +``` + + + +## `markdown()` + +compose a new telegram message (parsed as markdown) + +```php +Telegraph::markdown('*hello* world')->send(); +``` + +## `markdownV2()` + +compose a new telegram message (parsed as markdownV2) + +```php +Telegraph::markdownV2('*hello* world')->send(); +``` + + +## `html()` + +compose a new telegram message (parsed as html) + +```php +Telegraph::html('hello world')->send(); +``` + +## `when()` + +allows to execute a closure when the given condition is verified + +```php +Telegraph::when(true, fn(Telegraph $telegraph) => $telegraph->message('conditional message')->send()); +``` + + + +## `edit()` + +edits a message + +```php +Telegraph::edit($messageId)->markdown('new message')->send(); +``` + + + +## `document()` + +sends a document + +```php +Telegraph::document($documentPath)->send(); +``` + +## `location()` + +sends a location attachment + +```php +Telegraph::location(12.345, -54.321)->send(); +``` + +## `contact()` + +sens a contact attachment + +```php +Telegraph::contact('3331122111', 'firstName')->send(); +``` + +## `photo()` + +sends a photo + +```php +Telegraph::photo($pathToPhotoFile)->send(); +``` + +## `voice()` + +sends a vocal message + +```php +Telegraph::voice($pathToVoiceFile)->send(); +``` + +## `mediaGroup()` + +sends a group of photos, videos, documents or audios as an album + +```php +Telegraph::mediaGroup([ + [ + 'type' => 'photo', + 'media' => 'https://my-repository/photo1.jpg', + ], + [ + 'type' => 'photo', + 'media' => 'https://my-repository/photo2.jpg', + ] +])->send(); +``` + + + +## `editCaption()` + +edits an attachment caption + +```php +Telegraph::editCaption($messageId)->markdownV2('new caption')->send(); +``` + +## `editMedia()` + +edits a media messages with a new media content + +```php +Telegraph::editMedia($messageId)->photo($path)->send(); +Telegraph::editMedia($messageId)->document($path)->send(); +Telegraph::editMedia($messageId)->animation($path)->send(); +Telegraph::editMedia($messageId)->video($path)->send(); +Telegraph::editMedia($messageId)->audio($path)->send(); +``` + + +## `poll()` + +creates a native poll. For more info, see telegram [bot documentation](https://core.telegram.org/bots/api#sendpoll) + +```php +Telegraph::poll("What's your favourite programming language?") + ->option('php') + ->option('typescript') + ->option('rust') + ->allowMultipeAnswers() + ->validUntil(now()->addMinutes(5)) + ->send(); +``` + +## `quiz()` + +creates a quiz. For more info, see telegram [bot documentation](https://core.telegram.org/bots/api#sendpoll) + +```php +Telegraph::quiz("What's your favourite programming language?") + ->option('php', correct: true) + ->option('typescript') + ->option('rust') + ->explanation('We all love php, right?') + ->validUntil(now()->addMinutes(5)) + ->send(); +``` + + +## `thread()` + +set custom Telegraph Thread id + +```php +Telegraph::message('test')->inThread('thread_id'); +``` diff --git a/docs/13.api/4.webhooks.md b/docs/13.api/4.webhooks.md new file mode 100644 index 000000000..370ec82a7 --- /dev/null +++ b/docs/13.api/4.webhooks.md @@ -0,0 +1,29 @@ +--- +title: 'Webhooks API calls' +navigation.title: 'Webhooks' +--- + + + +## `answerInlineQuery()` + +send back the results for an inline query + +```php + Telegraph::answerInlineQuery($inlineQuery->id(), [ + InlineQueryResultPhoto::make($logo->id."-light", "https://logofinder.dev/$logo->id/light.jpg", "https://logofinder.dev/$logo->id/light/thumb.jpg") + ->caption('Light Logo'), + InlineQueryResultPhoto::make($logo->id."-dark", "https://logofinder.dev/$logo->id/dark.jpg", "https://logofinder.dev/$logo->id/dark/thumb.jpg") + ->caption('Dark Logo'), +])->cache(seconds: 600)->send(); +``` + + + +## `replyWebhook()` + +replies to a webhook callback + +```php +Telegraph::replyWebhook($callbackQueryId, 'message received', $showAlert)->send(); +``` diff --git a/docs/13.api/5.helpers.md b/docs/13.api/5.helpers.md new file mode 100644 index 000000000..ae94cb5d6 --- /dev/null +++ b/docs/13.api/5.helpers.md @@ -0,0 +1,30 @@ +--- +title: 'API calls helpers' +navigation.title: 'Helpers' +--- + + +## `dump()` + +print a `dump()` of the current api call status for testing purposes + +```php +Telegraph::message('test')->dump(); +``` + +## `dd()` + +print a `dd()` of the current api call status for testing purposes + +```php +Telegraph::message('test')->dd(); +``` + + +## `withData()` + +set custom Telegraph data attribute + +```php +Telegraph::withData('key', 'value'); +``` diff --git a/docs/13.models/1.telegraph-bot.md b/docs/14.models/1.telegraph-bot.md similarity index 100% rename from docs/13.models/1.telegraph-bot.md rename to docs/14.models/1.telegraph-bot.md diff --git a/docs/13.models/2.telegraph-chat.md b/docs/14.models/2.telegraph-chat.md similarity index 100% rename from docs/13.models/2.telegraph-chat.md rename to docs/14.models/2.telegraph-chat.md diff --git a/docs/14.webhooks/1.overview.md b/docs/15.webhooks/1.overview.md similarity index 100% rename from docs/14.webhooks/1.overview.md rename to docs/15.webhooks/1.overview.md diff --git a/docs/14.webhooks/2.registering-webhooks.md b/docs/15.webhooks/2.registering-webhooks.md similarity index 100% rename from docs/14.webhooks/2.registering-webhooks.md rename to docs/15.webhooks/2.registering-webhooks.md diff --git a/docs/14.webhooks/3.deleting-webhooks.md b/docs/15.webhooks/3.deleting-webhooks.md similarity index 100% rename from docs/14.webhooks/3.deleting-webhooks.md rename to docs/15.webhooks/3.deleting-webhooks.md diff --git a/docs/14.webhooks/4.webhook-request-types.md b/docs/15.webhooks/4.webhook-request-types.md similarity index 100% rename from docs/14.webhooks/4.webhook-request-types.md rename to docs/15.webhooks/4.webhook-request-types.md diff --git a/docs/14.webhooks/5.callback-data.md b/docs/15.webhooks/5.callback-data.md similarity index 100% rename from docs/14.webhooks/5.callback-data.md rename to docs/15.webhooks/5.callback-data.md diff --git a/docs/14.webhooks/6.callback-reply.md b/docs/15.webhooks/6.callback-reply.md similarity index 100% rename from docs/14.webhooks/6.callback-reply.md rename to docs/15.webhooks/6.callback-reply.md diff --git a/docs/14.webhooks/7.keyboard-interaction.md b/docs/15.webhooks/7.keyboard-interaction.md similarity index 100% rename from docs/14.webhooks/7.keyboard-interaction.md rename to docs/15.webhooks/7.keyboard-interaction.md diff --git a/docs/14.webhooks/8.manual-polling.md b/docs/15.webhooks/8.manual-polling.md similarity index 100% rename from docs/14.webhooks/8.manual-polling.md rename to docs/15.webhooks/8.manual-polling.md diff --git a/docs/15.storage/1.entities_storage.md b/docs/16.storage/1.entities_storage.md similarity index 100% rename from docs/15.storage/1.entities_storage.md rename to docs/16.storage/1.entities_storage.md diff --git a/docs/16.testing/1.fake.md b/docs/17.testing/1.fake.md similarity index 100% rename from docs/16.testing/1.fake.md rename to docs/17.testing/1.fake.md diff --git a/docs/16.testing/2.assertions.md b/docs/17.testing/2.assertions.md similarity index 100% rename from docs/16.testing/2.assertions.md rename to docs/17.testing/2.assertions.md diff --git a/docs/17.community/1.contributing.md b/docs/18.community/1.contributing.md similarity index 100% rename from docs/17.community/1.contributing.md rename to docs/18.community/1.contributing.md diff --git a/docs/17.community/2.translating.md b/docs/18.community/2.translating.md similarity index 100% rename from docs/17.community/2.translating.md rename to docs/18.community/2.translating.md diff --git a/docs/17.community/3.releases.md b/docs/18.community/3.releases.md similarity index 100% rename from docs/17.community/3.releases.md rename to docs/18.community/3.releases.md diff --git a/docs/17.community/4.changelog.md b/docs/18.community/4.changelog.md similarity index 100% rename from docs/17.community/4.changelog.md rename to docs/18.community/4.changelog.md