From 03d5173351217d01cd5548b69ca7236466855878 Mon Sep 17 00:00:00 2001 From: Daniil Gentili Date: Thu, 7 Dec 2023 20:14:38 +0100 Subject: [PATCH] Re-add docs for some methods --- README.md | 6 +++--- src/Namespace/Blacklist.php | 3 +++ src/Namespace/Channels.php | 12 ++++++++++++ src/Namespace/Messages.php | 29 +++++++++++++++++++++++++++++ 4 files changed, 47 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 251db7e67..b629956de 100644 --- a/README.md +++ b/README.md @@ -498,6 +498,7 @@ Want to add your own open-source project to this list? [Click here!](https://doc * Get changed emoji keywords ยป: messages.getEmojiKeywordsDifference * Get changelog of current app. : help.getAppChangelog * Get channel statistics: stats.getBroadcastStats + * Get channel/supergroup messages: channels.getMessages * Get channels/supergroups/geogroups we're admin in. Usually called when the user exceeds the limit for owned public channels/supergroups/geogroups, and the user is given the choice to remove one of his channels/supergroups/geogroups: channels.getAdminedPublicChannels * Get chats in common with a user: messages.getCommonChats * Get configuration for CDN file downloads: help.getCdnConfig @@ -728,9 +729,6 @@ Want to add your own open-source project to this list? [Click here!](https://doc * Pin/unpin a dialog: messages.toggleDialogPin * Play file in call: callPlay * Play files on hold in call: callPlayOnHold - * Please use the event handler: channels.getMessages - * Please use the event handler: messages.getHistory - * Please use the event handler: messages.getMessages * Positive modulo: posmod * Press an inline callback button and get a callback answer from the bot: messages.getBotCallbackAnswer * Provide a buffered reader for a file, URL or amp stream: openBuffered @@ -798,10 +796,12 @@ Want to add your own open-source project to this list? [Click here!](https://doc * Returns list of chats with non-default notification settings: account.getNotifyExceptions * Returns localized text of a text message with an invitation: help.getInviteText * Returns sparse positions of messages of the specified type in the chat to be used for shared media scroll implementation: messages.getSearchResultsPositions + * Returns the conversation history with one interlocutor / within a chat: messages.getHistory * Returns the current user dialog list: messages.getDialogs * Returns the current user's contact list: contacts.getContacts * Returns the list of blocked users: contacts.getBlocked * Returns the list of contact statuses: contacts.getStatuses + * Returns the list of messages by their IDs: messages.getMessages * Returns the list of user photos: photos.getUserPhotos * Returns the session name: getSessionName * Returns the support user for the "ask a question" feature: help.getSupport diff --git a/src/Namespace/Blacklist.php b/src/Namespace/Blacklist.php index 2ad33171f..5b556c25b 100644 --- a/src/Namespace/Blacklist.php +++ b/src/Namespace/Blacklist.php @@ -5,6 +5,9 @@ namespace danog\MadelineProto\Namespace; final class Blacklist { public const BLACKLIST = [ + '__messages.getHistory' => 'Please use the [event handler](https://docs.madelineproto.xyz/docs/UPDATES.html)', + '__channels.getMessages' => 'Please use the [event handler](https://docs.madelineproto.xyz/docs/UPDATES.html)', + '__messages.getMessages' => 'Please use the [event handler](https://docs.madelineproto.xyz/docs/UPDATES.html)', 'account.updatePasswordSettings' => 'You cannot use this method directly; use $MadelineProto->update2fa($params), instead (see https://docs.madelineproto.xyz for more info)', 'account.getPasswordSettings' => 'You cannot use this method directly; use $MadelineProto->update2fa($params), instead (see https://docs.madelineproto.xyz for more info)', 'messages.receivedQueue' => 'You cannot use this method directly', diff --git a/src/Namespace/Channels.php b/src/Namespace/Channels.php index 46701437b..ce7218345 100644 --- a/src/Namespace/Channels.php +++ b/src/Namespace/Channels.php @@ -44,6 +44,18 @@ interface Channels */ public function reportSpam(array|int|string|null $channel = null, array|int|string|null $participant = null, array $id = [], ?int $floodWaitLimit = null, bool $postpone = false, ?\Amp\Cancellation $cancellation = null): bool; + /** + * Get [channel/supergroup](https://core.telegram.org/api/channel) messages. + * + * @param array|int|string $channel Channel/supergroup @see https://docs.madelineproto.xyz/API_docs/types/InputChannel.html + * @param list|array $id Array of IDs of messages to get @see https://docs.madelineproto.xyz/API_docs/types/InputMessage.html + * @param ?int $floodWaitLimit Can be used to specify a custom flood wait limit: if a FLOOD_WAIT_ rate limiting error is received with a waiting period bigger than this integer, an RPCErrorException will be thrown; otherwise, MadelineProto will simply wait for the specified amount of time. Defaults to the value specified in the settings: https://docs.madelineproto.xyz/PHP/danog/MadelineProto/Settings/RPC.html#setfloodtimeout-int-floodtimeout-self + * @param bool $postpone If true, will postpone execution of this method until the first method call with $postpone = false to the same DC or a call to flush() is made, bundling all queued in a single container for higher efficiency. Will not return until the method is queued and a response is received, so this should be used in combination with \Amp\async. + * @param ?\Amp\Cancellation $cancellation Cancellation + * @return array{_: 'messages.messages', messages: list, chats: list, users: list}|array{_: 'messages.messagesSlice', inexact: array, count: array, next_rate: array, offset_id_offset: array, messages: list, chats: list, users: list}|array{_: 'messages.channelMessages', inexact: array, pts: array, count: array, offset_id_offset: array, messages: list, topics: list, chats: list, users: list}|array{_: 'messages.messagesNotModified', count: array} @see https://docs.madelineproto.xyz/API_docs/types/messages.Messages.html + */ + public function getMessages(array|int|string|null $channel = null, array $id = [], ?int $floodWaitLimit = null, bool $postpone = false, ?\Amp\Cancellation $cancellation = null): array; + /** * Get the participants of a [supergroup/channel](https://core.telegram.org/api/channel). * diff --git a/src/Namespace/Messages.php b/src/Namespace/Messages.php index 9ffb4ebd4..66854ba6e 100644 --- a/src/Namespace/Messages.php +++ b/src/Namespace/Messages.php @@ -9,6 +9,17 @@ namespace danog\MadelineProto\Namespace; interface Messages { + /** + * Returns the list of messages by their IDs. + * + * @param list|array $id Array of Message ID list @see https://docs.madelineproto.xyz/API_docs/types/InputMessage.html + * @param ?int $floodWaitLimit Can be used to specify a custom flood wait limit: if a FLOOD_WAIT_ rate limiting error is received with a waiting period bigger than this integer, an RPCErrorException will be thrown; otherwise, MadelineProto will simply wait for the specified amount of time. Defaults to the value specified in the settings: https://docs.madelineproto.xyz/PHP/danog/MadelineProto/Settings/RPC.html#setfloodtimeout-int-floodtimeout-self + * @param bool $postpone If true, will postpone execution of this method until the first method call with $postpone = false to the same DC or a call to flush() is made, bundling all queued in a single container for higher efficiency. Will not return until the method is queued and a response is received, so this should be used in combination with \Amp\async. + * @param ?\Amp\Cancellation $cancellation Cancellation + * @return array{_: 'messages.messages', messages: list, chats: list, users: list}|array{_: 'messages.messagesSlice', inexact: array, count: array, next_rate: array, offset_id_offset: array, messages: list, chats: list, users: list}|array{_: 'messages.channelMessages', inexact: array, pts: array, count: array, offset_id_offset: array, messages: list, topics: list, chats: list, users: list}|array{_: 'messages.messagesNotModified', count: array} @see https://docs.madelineproto.xyz/API_docs/types/messages.Messages.html + */ + public function getMessages(array $id = [], ?int $floodWaitLimit = null, bool $postpone = false, ?\Amp\Cancellation $cancellation = null): array; + /** * Returns the current user dialog list. * @@ -26,6 +37,24 @@ interface Messages */ public function getDialogs(bool|null $exclude_pinned = false, int|null $folder_id = 0, int|null $offset_date = 0, int|null $offset_id = 0, array|int|string|null $offset_peer = null, int|null $limit = 0, array $hash = [], ?int $floodWaitLimit = null, bool $postpone = false, ?\Amp\Cancellation $cancellation = null): array; + /** + * Returns the conversation history with one interlocutor / within a chat. + * + * @param array|int|string $peer Target peer @see https://docs.madelineproto.xyz/API_docs/types/InputPeer.html + * @param int $offset_id Only return messages starting from the specified message ID + * @param int $offset_date Only return messages sent before the specified date + * @param int $add_offset Number of list elements to be skipped, negative values are also accepted. + * @param int $limit Number of results to return + * @param int $max_id If a positive value was transferred, the method will return only messages with IDs less than **max\_id** + * @param int $min_id If a positive value was transferred, the method will return only messages with IDs more than **min\_id** + * @param list|array $hash [Result hash](https://core.telegram.org/api/offsets) + * @param ?int $floodWaitLimit Can be used to specify a custom flood wait limit: if a FLOOD_WAIT_ rate limiting error is received with a waiting period bigger than this integer, an RPCErrorException will be thrown; otherwise, MadelineProto will simply wait for the specified amount of time. Defaults to the value specified in the settings: https://docs.madelineproto.xyz/PHP/danog/MadelineProto/Settings/RPC.html#setfloodtimeout-int-floodtimeout-self + * @param bool $postpone If true, will postpone execution of this method until the first method call with $postpone = false to the same DC or a call to flush() is made, bundling all queued in a single container for higher efficiency. Will not return until the method is queued and a response is received, so this should be used in combination with \Amp\async. + * @param ?\Amp\Cancellation $cancellation Cancellation + * @return array{_: 'messages.messages', messages: list, chats: list, users: list}|array{_: 'messages.messagesSlice', inexact: array, count: array, next_rate: array, offset_id_offset: array, messages: list, chats: list, users: list}|array{_: 'messages.channelMessages', inexact: array, pts: array, count: array, offset_id_offset: array, messages: list, topics: list, chats: list, users: list}|array{_: 'messages.messagesNotModified', count: array} @see https://docs.madelineproto.xyz/API_docs/types/messages.Messages.html + */ + public function getHistory(array|int|string|null $peer = null, int|null $offset_id = 0, int|null $offset_date = 0, int|null $add_offset = 0, int|null $limit = 0, int|null $max_id = 0, int|null $min_id = 0, array $hash = [], ?int $floodWaitLimit = null, bool $postpone = false, ?\Amp\Cancellation $cancellation = null): array; + /** * Returns found messages. *