Search moodle.org's
Developer Documentation
Developer Documentation
- Bug fixes for general core bugs in 4.0.x will end 8 May 2023 (12 months).
- Bug fixes for security issues in 4.0.x will end 13 November 2023 (18 months).
- PHP version: minimum PHP 7.3.0 Note: the minimum PHP version has increased since Moodle 3.10. PHP 7.4.x is also supported.
/message/classes/ -> api.php (source)
Differences Between: [Versions 310 and 400] [Versions 311 and 400] [Versions 39 and 400] [Versions 400 and 401] [Versions 400 and 402] [Versions 400 and 403]
Contains class used to return information to display for the message area.
| Copyright: | 2016 Mark Nelson <markn@moodle.com> |
| License: | http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later |
| File Size: | 3094 lines (134 kb) |
| Included or required: | 0 times |
| Referenced: | 0 times |
| Includes or requires: | 0 files |
Defines 1 class
api:: (87 methods):
search_messages()
search_users_in_course()
search_users()
message_search_users()
get_linked_conversation_extra_fields()
get_conversations()
get_conversations_between_users()
get_conversation()
set_favourite_conversation()
unset_favourite_conversation()
get_contacts()
get_user_contacts()
count_contacts()
get_contacts_with_unread_message_count()
get_non_contacts_with_unread_message_count()
get_messages()
get_conversation_messages()
get_most_recent_message()
get_most_recent_conversation_message()
get_profile()
can_delete_conversation()
delete_conversation()
delete_conversation_by_id()
count_unread_conversations()
can_mark_all_messages_as_read()
get_conversation_counts()
mark_all_messages_as_read()
mark_all_notifications_as_read()
mark_all_read_for_user()
get_all_message_preferences()
count_blocked_users()
can_post_message()
can_send_message()
can_send_message_to_conversation()
send_message_to_conversation()
get_user_privacy_messaging_preference()
is_user_non_contact_blocked()
is_user_blocked()
get_message_processor()
is_processor_enabled()
update_processor_status()
get_processed_processor_object()
get_blocked_users()
mark_message_as_read()
mark_notification_as_read()
can_delete_message()
delete_message()
get_conversation_between_users()
get_individual_conversations_between_users()
get_self_conversation()
create_conversation_between_users()
create_conversation()
can_create_group_conversation()
can_create_contact()
create_contact_request()
confirm_contact_request()
decline_contact_request()
get_contact_requests()
get_received_contact_requests_count()
add_contact()
remove_contact()
block_user()
unblock_user()
is_contact()
get_contact()
is_blocked()
get_contact_requests_between_users()
does_contact_request_exist()
is_user_in_conversation()
can_contact_user()
add_members_to_conversation()
remove_members_from_conversation()
count_conversation_members()
is_conversation_area_enabled()
get_conversation_by_area()
enable_conversation()
disable_conversation()
update_conversation_name()
get_conversation_members()
get_unread_conversation_counts()
mute_conversation()
unmute_conversation()
is_conversation_muted()
delete_all_conversation_data()
can_delete_message_for_all_users()
delete_message_for_all_users()
lazy_create_self_conversation()
Class used to return information to display for the message area.
| search_messages($userid, $search, $limitfrom = 0, $limitnum = 0) X-Ref |
| Handles searching for messages in the message area. return: array param: int $userid The user id doing the searching param: string $search The string the user is searching param: int $limitfrom param: int $limitnum |
| search_users_in_course() X-Ref |
| search_users() X-Ref |
| message_search_users(int $userid, string $search, int $limitfrom = 0, int $limitnum = 20) X-Ref |
| Handles searching for user. return: array param: int $userid The user id doing the searching param: string $search The string the user is searching param: int $limitfrom param: int $limitnum |
| get_linked_conversation_extra_fields(array $conversations) X-Ref |
| Gets extra fields, like image url and subname for any conversations linked to components. The subname is like a subtitle for the conversation, to compliment it's name. The imageurl is the location of the image for the conversation, as might be seen on a listing of conversations for a user. return: array the array of subnames, index by conversation id. param: array $conversations a list of conversations records. |
| get_conversations($userid, $limitfrom = 0, $limitnum = 20, int $type = null,bool $favourites = null, bool $mergeself = false) X-Ref |
| Returns the contacts and their conversation to display in the contacts area. ** WARNING ** It is HIGHLY recommended to use a sensible limit when calling this function. Trying to retrieve too much information in a single call will cause performance problems. ** WARNING ** This function has specifically been altered to break each of the data sets it requires into separate database calls. This is to avoid the performance problems observed when attempting to join large data sets (e.g. the message tables and the user table). While it is possible to gather the data in a single query, and it may even be more efficient with a correctly tuned database, we have opted to trade off some of the benefits of a single query in order to ensure this function will work on most databases with default tunings and with large data sets. return: array the array of conversations param: int $userid The user id param: int $limitfrom param: int $limitnum param: int $type the type of the conversation, if you wish to filter to a certain type (see api constants). param: bool $favourites whether to include NO favourites (false) or ONLY favourites (true), or null to ignore this setting. param: bool $mergeself whether to include self-conversations (true) or ONLY private conversations (false) |
| get_conversations_between_users(int $userid1, int $userid2,int $limitfrom = 0, int $limitnum = 20) X-Ref |
| Returns all conversations between two users return: array param: int $userid1 One of the user's id param: int $userid2 The other user's id param: int $limitfrom param: int $limitnum |
| get_conversation(int $userid,int $conversationid,bool $includecontactrequests = false,bool $includeprivacyinfo = false,int $memberlimit = 0,int $memberoffset = 0,int $messagelimit = 0,int $messageoffset = 0,bool $newestmessagesfirst = true) X-Ref |
| Return a conversation. return: \stdClass param: int $userid The user id to get the conversation for param: int $conversationid The id of the conversation to fetch param: bool $includecontactrequests Should contact requests be included between members param: bool $includeprivacyinfo Should privacy info be included between members param: int $memberlimit Limit number of members to load param: int $memberoffset Offset members by this amount param: int $messagelimit Limit number of messages to load param: int $messageoffset Offset the messages param: bool $newestmessagesfirst Order messages by newest first |
| set_favourite_conversation(int $conversationid, int $userid) X-Ref |
| Mark a conversation as a favourite for the given user. return: favourite the favourite object. param: int $conversationid the id of the conversation to mark as a favourite. param: int $userid the id of the user to whom the favourite belongs. |
| unset_favourite_conversation(int $conversationid, int $userid) X-Ref |
| Unset a conversation as a favourite for the given user. param: int $conversationid the id of the conversation to unset as a favourite. param: int $userid the id to whom the favourite belongs. |
| get_contacts() X-Ref |
| get_user_contacts(int $userid, int $limitfrom = 0, int $limitnum = 0) X-Ref |
| Get the contacts for a given user. return: array An array of contacts param: int $userid param: int $limitfrom param: int $limitnum |
| count_contacts(int $userid) X-Ref |
| Returns the contacts count. return: array param: int $userid The user id |
| get_contacts_with_unread_message_count($userid, $limitfrom = 0, $limitnum = 0) X-Ref |
| Returns the an array of the users the given user is in a conversation with who are a contact and the number of unread messages. return: array param: int $userid The user id param: int $limitfrom param: int $limitnum |
| get_non_contacts_with_unread_message_count($userid, $limitfrom = 0, $limitnum = 0) X-Ref |
| Returns the an array of the users the given user is in a conversation with who are not a contact and the number of unread messages. return: array param: int $userid The user id param: int $limitfrom param: int $limitnum |
| get_messages() X-Ref |
| get_conversation_messages(int $userid, int $convid, int $limitfrom = 0, int $limitnum = 0,string $sort = 'timecreated ASC', int $timefrom = 0, int $timeto = 0) X-Ref |
| Returns the messages for the defined conversation. return: array of messages param: int $userid The current user. param: int $convid The conversation where the messages belong. Could be an object or just the id. param: int $limitfrom Return a subset of records, starting at this point (optional). param: int $limitnum Return a subset comprising this many records in total (optional, required if $limitfrom is set). param: string $sort The column name to order by including optionally direction. param: int $timefrom The time from the message being sent. param: int $timeto The time up until the message being sent. |
| get_most_recent_message() X-Ref |
| get_most_recent_conversation_message(int $convid, int $currentuserid = 0) X-Ref |
| Returns the most recent message in a conversation. return: \stdClass|null The most recent message. param: int $convid The conversation identifier. param: int $currentuserid The current user identifier. |
| get_profile() X-Ref |
| can_delete_conversation(int $userid, int $conversationid = null) X-Ref |
| Checks if a user can delete messages they have either received or sent. return: bool Returns true if a user can delete the conversation, false otherwise. param: int $userid The user id of who we want to delete the messages for (this may be done by the admin param: int $conversationid The id of the conversation |
| delete_conversation() X-Ref |
| delete_conversation_by_id(int $userid, int $conversationid) X-Ref |
| Deletes a conversation for a specified user. This function does not verify any permissions. param: int $userid The user id of who we want to delete the messages for (this may be done by the admin param: int $conversationid The id of the other user in the conversation |
| count_unread_conversations($user = null) X-Ref |
| Returns the count of unread conversations (collection of messages from a single user) for the given user. return: int the count of the user's unread conversations param: \stdClass $user the user who's conversations should be counted |
| can_mark_all_messages_as_read(int $userid, int $conversationid) X-Ref |
| Checks if a user can mark all messages as read. return: bool true if user is permitted, false otherwise param: int $userid The user id of who we want to mark the messages for param: int $conversationid The id of the conversation |
| get_conversation_counts(int $userid) X-Ref |
| Returns the count of conversations (collection of messages from a single user) for the given user. return: array the array of conversations counts, indexed by type. param: int $userid The user whose conversations should be counted. |
| mark_all_messages_as_read($userid, $conversationid = null) X-Ref |
| Marks all messages being sent to a user in a particular conversation. If $conversationdid is null then it marks all messages as read sent to $userid. param: int $userid param: int|null $conversationid The conversation the messages belong to mark as read, if null mark all |
| mark_all_notifications_as_read($touserid, $fromuserid = null, $timecreatedto = null) X-Ref |
| Marks all notifications being sent from one user to another user as read. If the from user is null then it marks all notifications as read sent to the to user. return: void param: int $touserid the id of the message recipient param: int|null $fromuserid the id of the message sender, null if all messages param: int|null $timecreatedto mark notifications created before this time as read |
| mark_all_read_for_user() X-Ref |
| get_all_message_preferences($processors, $providers, $user) X-Ref |
| Returns message preferences. return: \stdClass param: array $processors param: array $providers param: \stdClass $user |
| count_blocked_users($user = null) X-Ref |
| Count the number of users blocked by a user. return: int the number of blocked users param: \stdClass $user The user object |
| can_post_message() X-Ref |
| can_send_message(int $recipientid, int $senderid, bool $evenifblocked = false) X-Ref |
| Determines if a user is permitted to send another user a private message. return: bool true if user is permitted, false otherwise. param: int $recipientid The recipient user id. param: int $senderid The sender user id. param: bool $evenifblocked This lets the user know, that even if the recipient has blocked the user |
| can_send_message_to_conversation(int $userid, int $conversationid) X-Ref |
| Determines if a user is permitted to send a message to a given conversation. If no sender is provided then it defaults to the logged in user. return: bool true if the user can send a message to the conversation, false otherwise. param: int $userid the id of the user on which the checks will be applied. param: int $conversationid the id of the conversation we wish to check. |
| send_message_to_conversation(int $userid, int $conversationid, string $message,int $format) X-Ref |
| Send a message from a user to a conversation. This method will create the basic eventdata and delegate to message creation to message_send. The message_send() method is responsible for event data that is specific to each recipient. return: \stdClass the message created. param: int $userid the sender id. param: int $conversationid the conversation id. param: string $message the message to send. param: int $format the format of the message to send. |
| get_user_privacy_messaging_preference(int $userid) X-Ref |
| Get the messaging preference for a user. If the user has not any messaging privacy preference: - When $CFG->messagingallusers = false the default user preference is MESSAGE_PRIVACY_COURSEMEMBER. - When $CFG->messagingallusers = true the default user preference is MESSAGE_PRIVACY_SITE. return: int The default messaging preference. param: int $userid The user identifier. |
| is_user_non_contact_blocked() X-Ref |
| is_user_blocked() X-Ref |
| get_message_processor($name, $ready = false) X-Ref |
| Get specified message processor, validate corresponding plugin existence and system configuration. return: mixed $processor if processor present else empty array. param: string $name Name of the processor. param: bool $ready only return ready-to-use processors. |
| is_processor_enabled($name) X-Ref |
| Returns weather a given processor is enabled or not. Note:- This doesn't check if the processor is configured or not. return: bool param: string $name Name of the processor |
| update_processor_status($processor, $enabled) X-Ref |
| Set status of a processor. return: bool param: \stdClass $processor processor record. param: 0|1 $enabled 0 or 1 to set the processor status. |
| get_processed_processor_object(\stdClass $processor) X-Ref |
| Given a processor object, loads information about it's settings and configurations. This is not a public api, instead use @see \core_message\api::get_message_processor() or @see \get_message_processors() return: \stdClass processed processor object param: \stdClass $processor processor object |
| get_blocked_users($userid) X-Ref |
| Retrieve users blocked by $user1 return: array the users blocked param: int $userid The user id of the user whos blocked users we are returning |
| mark_message_as_read($userid, $message, $timeread = null) X-Ref |
| Mark a single message as read. param: int $userid The user id who marked the message as read param: \stdClass $message The message param: int|null $timeread The time the message was marked as read, if null will default to time() |
| mark_notification_as_read($notification, $timeread = null) X-Ref |
| Mark a single notification as read. param: \stdClass $notification The notification param: int|null $timeread The time the message was marked as read, if null will default to time() |
| can_delete_message($userid, $messageid) X-Ref |
| Checks if a user can delete a message. return: bool Returns true if a user can delete the message, false otherwise. param: int $userid the user id of who we want to delete the message for (this may be done by the admin param: int $messageid The message id |
| delete_message($userid, $messageid) X-Ref |
| Deletes a message. This function does not verify any permissions. return: bool param: int $userid the user id of who we want to delete the message for (this may be done by the admin param: int $messageid The message id |
| get_conversation_between_users(array $userids) X-Ref |
| Returns the conversation between two users. return: int|bool The id of the conversation, false if not found param: array $userids |
| get_individual_conversations_between_users() X-Ref |
| get_self_conversation(int $userid) X-Ref |
| Returns the self conversation for a user. return: \stdClass|false The self-conversation object or false if it doesn't exist param: int $userid The user id to get the self-conversations |
| create_conversation_between_users() X-Ref |
| create_conversation(int $type, array $userids, string $name = null,int $enabled = self::MESSAGE_CONVERSATION_ENABLED, string $component = null,string $itemtype = null, int $itemid = null, int $contextid = null) X-Ref |
| Creates a conversation with selected users and messages. return: \stdClass param: int $type The type of conversation param: int[] $userids The array of users to add to the conversation param: string|null $name The name of the conversation param: int $enabled Determines if the conversation is created enabled or disabled param: string|null $component Defines the Moodle component which the conversation belongs to, if any param: string|null $itemtype Defines the type of the component param: int|null $itemid The id of the component param: int|null $contextid The id of the context |
| can_create_group_conversation(int $userid, \context $context) X-Ref |
| Checks if a user can create a group conversation. return: bool param: int $userid The id of the user attempting to create the conversation param: \context $context The context they are creating the conversation from, most likely course context |
| can_create_contact(int $userid, int $requesteduserid) X-Ref |
| Checks if a user can create a contact request. return: bool param: int $userid The id of the user who is creating the contact request param: int $requesteduserid The id of the user being requested |
| create_contact_request(int $userid, int $requesteduserid) X-Ref |
| Handles creating a contact request. return: \stdClass the request param: int $userid The id of the user who is creating the contact request param: int $requesteduserid The id of the user being requested |
| confirm_contact_request(int $userid, int $requesteduserid) X-Ref |
| Handles confirming a contact request. param: int $userid The id of the user who created the contact request param: int $requesteduserid The id of the user confirming the request |
| decline_contact_request(int $userid, int $requesteduserid) X-Ref |
| Handles declining a contact request. param: int $userid The id of the user who created the contact request param: int $requesteduserid The id of the user declining the request |
| get_contact_requests(int $userid, int $limitfrom = 0, int $limitnum = 0) X-Ref |
| Handles returning the contact requests for a user. This also includes the user data necessary to display information about the user. It will not include blocked users. return: array The list of contact requests param: int $userid param: int $limitfrom param: int $limitnum |
| get_received_contact_requests_count(int $userid) X-Ref |
| Returns the number of contact requests the user has received. return: int The count param: int $userid The ID of the user we want to return the number of received contact requests for |
| add_contact(int $userid, int $contactid) X-Ref |
| Handles adding a contact. param: int $userid The id of the user who requested to be a contact param: int $contactid The id of the contact |
| remove_contact(int $userid, int $contactid) X-Ref |
| Handles removing a contact. param: int $userid The id of the user who is removing a user as a contact param: int $contactid The id of the user to be removed as a contact |
| block_user(int $userid, int $usertoblockid) X-Ref |
| Handles blocking a user. param: int $userid The id of the user who is blocking param: int $usertoblockid The id of the user being blocked |
| unblock_user(int $userid, int $usertounblockid) X-Ref |
| Handles unblocking a user. param: int $userid The id of the user who is unblocking param: int $usertounblockid The id of the user being unblocked |
| is_contact(int $userid, int $contactid) X-Ref |
| Checks if users are already contacts. return: bool Returns true if they are a contact, false otherwise param: int $userid The id of one of the users param: int $contactid The id of the other user |
| get_contact(int $userid, int $contactid) X-Ref |
| Returns the row in the database table message_contacts that represents the contact between two people. return: mixed A fieldset object containing the record, false otherwise param: int $userid The id of one of the users param: int $contactid The id of the other user |
| is_blocked(int $userid, int $blockeduserid) X-Ref |
| Checks if a user is already blocked. return: bool Returns true if they are a blocked, false otherwise param: int $userid param: int $blockeduserid |
| get_contact_requests_between_users(int $userid, int $requesteduserid) X-Ref |
| Get contact requests between users. return: \stdClass[] param: int $userid The id of the user who is creating the contact request param: int $requesteduserid The id of the user being requested |
| does_contact_request_exist(int $userid, int $requesteduserid) X-Ref |
| Checks if a contact request already exists between users. return: bool Returns true if a contact request exists, false otherwise param: int $userid The id of the user who is creating the contact request param: int $requesteduserid The id of the user being requested |
| is_user_in_conversation(int $userid, int $conversationid) X-Ref |
| Checks if a user is already in a conversation. return: bool Returns true if a contact request exists, false otherwise param: int $userid The id of the user we want to check if they are in a group param: int $conversationid The id of the conversation |
| can_contact_user(int $recipientid, int $senderid, bool $evenifblocked = false) X-Ref |
| Checks if the sender can message the recipient. return: bool true if recipient hasn't blocked sender and sender can contact to recipient, false otherwise. param: int $recipientid param: int $senderid param: bool $evenifblocked This lets the user know, that even if the recipient has blocked the user |
| add_members_to_conversation(array $userids, int $convid) X-Ref |
| Add some new members to an existing conversation. param: array $userids User ids array to add as members. param: int $convid The conversation id. Must exists. |
| remove_members_from_conversation(array $userids, int $convid) X-Ref |
| Remove some members from an existing conversation. param: array $userids The user ids to remove from conversation members. param: int $convid The conversation id. Must exists. |
| count_conversation_members(int $convid) X-Ref |
| Count conversation members. return: int Number of conversation members. param: int $convid The conversation id. |
| is_conversation_area_enabled(string $component, string $itemtype, int $itemid, int $contextid) X-Ref |
| Checks whether or not a conversation area is enabled. return: bool Returns if a conversation area exists and is enabled, false otherwise param: string $component Defines the Moodle component which the area was added to. param: string $itemtype Defines the type of the component. param: int $itemid The id of the component. param: int $contextid The id of the context. |
| get_conversation_by_area(string $component, string $itemtype, int $itemid, int $contextid) X-Ref |
| Get conversation by area. return: \stdClass param: string $component Defines the Moodle component which the area was added to. param: string $itemtype Defines the type of the component. param: int $itemid The id of the component. param: int $contextid The id of the context. |
| enable_conversation(int $conversationid) X-Ref |
| Enable a conversation. return: void param: int $conversationid The id of the conversation. |
| disable_conversation(int $conversationid) X-Ref |
| Disable a conversation. return: void param: int $conversationid The id of the conversation. |
| update_conversation_name(int $conversationid, string $name) X-Ref |
| Update the name of a conversation. return: void param: int $conversationid The id of a conversation. param: string $name The main name of the area |
| get_conversation_members(int $userid, int $conversationid, bool $includecontactrequests = false,bool $includeprivacyinfo = false, int $limitfrom = 0,int $limitnum = 0) X-Ref |
| Returns a list of conversation members. return: array param: int $userid The user we are returning the conversation members for, used by helper::get_member_info. param: int $conversationid The id of the conversation param: bool $includecontactrequests Do we want to include contact requests with this data? param: bool $includeprivacyinfo Do we want to include privacy requests with this data? param: int $limitfrom param: int $limitnum |
| get_unread_conversation_counts(int $userid) X-Ref |
| Get the unread counts for all conversations for the user, sorted by type, and including favourites. return: array the unread counts for each conversation, indexed by type. param: int $userid the id of the user whose conversations we'll check. |
| mute_conversation(int $userid, int $conversationid) X-Ref |
| Handles muting a conversation. param: int $userid The id of the user param: int $conversationid The id of the conversation |
| unmute_conversation(int $userid, int $conversationid) X-Ref |
| Handles unmuting a conversation. param: int $userid The id of the user param: int $conversationid The id of the conversation |
| is_conversation_muted(int $userid, int $conversationid) X-Ref |
| Checks whether a conversation is muted or not. return: bool Whether or not the conversation is muted or not param: int $userid The id of the user param: int $conversationid The id of the conversation |
| delete_all_conversation_data(int $conversationid) X-Ref |
| Completely removes all related data in the DB for a given conversation. param: int $conversationid The id of the conversation |
| can_delete_message_for_all_users(int $userid, int $messageid) X-Ref |
| Checks if a user can delete a message for all users. return: bool Returns true if a user can delete the message for all users, false otherwise. param: int $userid the user id of who we want to delete the message for all users param: int $messageid The message id |
| delete_message_for_all_users(int $messageid) X-Ref |
| Delete a message for all users. This function does not verify any permissions. return: void param: int $messageid The message id |
| lazy_create_self_conversation(int $userid) X-Ref |
| Create a self conversation for a user, only if one doesn't already exist. param: int $userid the user to whom the conversation belongs. |
