Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

  • Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
  • Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
  • PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.

Differences Between: [Versions 310 and 401] [Versions 311 and 401] [Versions 39 and 401] [Versions 400 and 401] [Versions 401 and 402] [Versions 401 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: 3107 lines (135 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: api  - X-Ref

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.

param: int $userid The user id doing the searching
param: string $search The string the user is searching
param: int $limitfrom
param: int $limitnum
return: array

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.

param: int $userid The user id doing the searching
param: string $search The string the user is searching
param: int $limitfrom
param: int $limitnum
return: array

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.

param: array $conversations a list of conversations records.
return: array the array of subnames, index by conversation id.

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.

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)
return: array the array of conversations

get_conversations_between_users(int $userid1, int $userid2,int $limitfrom = 0, int $limitnum = 20)   X-Ref
Returns all conversations between two users

param: int $userid1 One of the user's id
param: int $userid2 The other user's id
param: int $limitfrom
param: int $limitnum
return: array

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.

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
return: \stdClass

set_favourite_conversation(int $conversationid, int $userid)   X-Ref
Mark a conversation as a favourite for the given user.

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.
return: favourite the favourite object.

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.

param: int $userid
param: int $limitfrom
param: int $limitnum
return: array An array of contacts

count_contacts(int $userid)   X-Ref
Returns the contacts count.

param: int $userid The user id
return: array

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.

param: int $userid The user id
param: int $limitfrom
param: int $limitnum
return: array

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.

param: int $userid The user id
param: int $limitfrom
param: int $limitnum
return: array

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.

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.
return: array of messages

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.

param: int $convid The conversation identifier.
param: int $currentuserid The current user identifier.
return: \stdClass|null The most recent message.

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.

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
return: bool Returns true if a user can delete the conversation, false otherwise.

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.

param: \stdClass $user the user who's conversations should be counted
return: int the count of the user's unread conversations

can_mark_all_messages_as_read(int $userid, int $conversationid)   X-Ref
Checks if a user can mark all messages as read.

param: int $userid The user id of who we want to mark the messages for
param: int $conversationid The id of the conversation
return: bool true if user is permitted, false otherwise

get_conversation_counts(int $userid)   X-Ref
Returns the count of conversations (collection of messages from a single user) for
the given user.

param: int $userid The user whose conversations should be counted.
return: array the array of conversations counts, indexed by type.

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.

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
return: void

mark_all_read_for_user()   X-Ref


get_all_message_preferences($processors, $providers, $user)   X-Ref
Returns message preferences.

param: array $processors
param: array $providers
param: \stdClass $user
return: \stdClass

count_blocked_users($user = null)   X-Ref
Count the number of users blocked by a user.

param: \stdClass $user The user object
return: int the number of blocked users

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.

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
return: bool true if user is permitted, false otherwise.

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.

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.
return: bool true if the user can send a message to the conversation, false otherwise.

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.

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.
return: \stdClass the message created.

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.

param: int    $userid The user identifier.
return: int    The default messaging preference.

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.

param: string $name  Name of the processor.
param: bool $ready only return ready-to-use processors.
return: mixed $processor if processor present else empty array.

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.

param: string $name Name of the processor
return: bool

update_processor_status($processor, $enabled)   X-Ref
Set status of a processor.

param: \stdClass $processor processor record.
param: 0|1 $enabled 0 or 1 to set the processor status.
return: bool

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()

param: \stdClass $processor processor object
return: \stdClass processed processor object

get_blocked_users($userid)   X-Ref
Retrieve users blocked by $user1

param: int $userid The user id of the user whos blocked users we are returning
return: array the users blocked

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.

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
return: bool Returns true if a user can delete the message, false otherwise.

delete_message($userid, $messageid)   X-Ref
Deletes a message.

This function does not verify any permissions.

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
return: bool

get_conversation_between_users(array $userids)   X-Ref
Returns the conversation between two users.

param: array $userids
return: int|bool The id of the conversation, false if not found

get_individual_conversations_between_users()   X-Ref


get_self_conversation(int $userid)   X-Ref
Returns the self conversation for a user.

param: int $userid The user id to get the self-conversations
return: \stdClass|false The self-conversation object or false if it doesn't exist

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.

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
return: \stdClass

can_create_group_conversation(int $userid, \context $context)   X-Ref
Checks if a user can create a group conversation.

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
return: bool

can_create_contact(int $userid, int $requesteduserid)   X-Ref
Checks if a user can create a contact 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
return: bool

create_contact_request(int $userid, int $requesteduserid)   X-Ref
Handles creating a contact 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
return: \stdClass the request

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.

param: int $userid
param: int $limitfrom
param: int $limitnum
return: array The list of contact requests

get_received_contact_requests_count(int $userid)   X-Ref
Returns the number of contact requests the user has received.

param: int $userid The ID of the user we want to return the number of received contact requests for
return: int The count

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.

param: int $userid The id of one of the users
param: int $contactid The id of the other user
return: bool Returns true if they are a contact, false otherwise

get_contact(int $userid, int $contactid)   X-Ref
Returns the row in the database table message_contacts that represents the contact between two people.

param: int $userid The id of one of the users
param: int $contactid The id of the other user
return: mixed A fieldset object containing the record, false otherwise

is_blocked(int $userid, int $blockeduserid)   X-Ref
Checks if a user is already blocked.

param: int $userid
param: int $blockeduserid
return: bool Returns true if they are a blocked, false otherwise

get_contact_requests_between_users(int $userid, int $requesteduserid)   X-Ref
Get contact requests between users.

param: int $userid The id of the user who is creating the contact request
param: int $requesteduserid The id of the user being requested
return: \stdClass[]

does_contact_request_exist(int $userid, int $requesteduserid)   X-Ref
Checks if a contact request already exists between users.

param: int $userid The id of the user who is creating the contact request
param: int $requesteduserid The id of the user being requested
return: bool Returns true if a contact request exists, false otherwise

is_user_in_conversation(int $userid, int $conversationid)   X-Ref
Checks if a user is already in a conversation.

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
return: bool Returns true if a contact request exists, false otherwise

can_contact_user(int $recipientid, int $senderid, bool $evenifblocked = false)   X-Ref
Checks if the sender can message the recipient.

param: int $recipientid
param: int $senderid
param: bool $evenifblocked This lets the user know, that even if the recipient has blocked the user
return: bool true if recipient hasn't blocked sender and sender can contact to recipient, false otherwise.

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.

param: int $convid The conversation id.
return: int Number of conversation members.

is_conversation_area_enabled(string $component, string $itemtype, int $itemid, int $contextid)   X-Ref
Checks whether or not a conversation area is enabled.

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.
return: bool Returns if a conversation area exists and is enabled, false otherwise

get_conversation_by_area(string $component, string $itemtype, int $itemid, int $contextid)   X-Ref
Get conversation by area.

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.
return: \stdClass

enable_conversation(int $conversationid)   X-Ref
Enable a conversation.

param: int $conversationid The id of the conversation.
return: void

disable_conversation(int $conversationid)   X-Ref
Disable a conversation.

param: int $conversationid The id of the conversation.
return: void

update_conversation_name(int $conversationid, string $name)   X-Ref
Update the name of a conversation.

param: int $conversationid The id of a conversation.
param: string $name The main name of the area
return: void

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.

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
return: array

get_unread_conversation_counts(int $userid)   X-Ref
Get the unread counts for all conversations for the user, sorted by type, and including favourites.

param: int $userid the id of the user whose conversations we'll check.
return: array the unread counts for each conversation, indexed by type.

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.

param: int $userid The id of the user
param: int $conversationid The id of the conversation
return: bool Whether or not the conversation is muted or not

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.

param: int $userid the user id of who we want to delete the message for all users
param: int $messageid The message id
return: bool Returns true if a user can delete the message for all users, false otherwise.

delete_message_for_all_users(int $messageid)   X-Ref
Delete a message for all users.

This function does not verify any permissions.

param: int $messageid The message id
return: void

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.