Moodle PHP Documentation 4.2
Moodle 4.2.8 (Build: 20240610) (2d41ac46f45)
core_message

Namespaces

namespace  core\message
  
 
namespace  core\message\inbound
  
 
namespace  core_message
  
 
namespace  core_message\external
  
 
namespace  core_message\output
  
 
namespace  core_message\output\preferences
  
 
namespace  core_message\privacy
  
 
namespace  core_message\search
  
 
namespace  core_message\task
  
 
namespace  core_message\tests
  
 

Classes

class  behat_message
 Messaging system steps definitions. More...
 
class  core\message\inbound\address_manager
 Incoming Message address manager. More...
 
class  core\message\inbound\handler
 
class  core\message\inbound\manager
 Variable Envelope Return Path manager class. More...
 
class  core\message\inbound\private_files_handler
 A Handler to store attachments sent in e-mails as private files. More...
 
class  core\message\inbound\processing_failed_exception
 Variable Envelope Return Path message processing failure exception. More...
 
class  core\message\message
 New messaging class. More...
 
class  core_message\external\get_unread_notification_count
 
class  core_message\helper
 Helper class for the message area. More...
 
class  core_message\output\preferences\message_notification_list
 Class to create context for the list of notifications on the message preferences page. More...
 
class  core_message\output\preferences\message_notification_list_component
 Class to create context for a notification component on the message preferences page. More...
 
class  core_message\output\preferences\notification_list
 Class to create context for the list of notifications on the message preferences page. More...
 
class  core_message\output\preferences\notification_list_component
 Class to create context for a notification component on the message preferences page. More...
 
class  core_message\output\preferences\notification_list_processor
 Class to create context for a notification component on the message preferences page. More...
 
class  core_message\output\preferences\processor
 Class to create context for one of the message processors settings on the message preferences page. More...
 
class  core_message\output\processor
 Class to prepare a message processor for display. More...
 
class  core_message\privacy\provider
 Privacy Subsystem implementation for core_message. More...
 
class  core_message\search\base_message
 Search area base class for messages. More...
 
class  core_message\search\message_received
 Search area for received messages. More...
 
class  core_message\search\message_sent
 Search area for sent messages. More...
 
class  core_message\task\migrate_message_data
 Class handling migrating data to the new messaging table schema. More...
 
class  core_message\tests\helper
 The helper class providing util methods for testing. More...
 
class  core_message\time_last_message_between_users
 Cache data source for the time of the last message in a conversation. More...
 
class  core_message_external
 Message external functions. More...
 
class  core_message_renderer
 message Renderer More...
 
class  message_output
 Base message processor class for extension by message processors. More...
 

Functions

 core_message_can_edit_message_profile ($user)
 Checks if current user is allowed to edit messaging preferences of another user.
 
 core_message_standard_after_main_region_html ()
 Render the message drawer to be included in the top of the body of each page.
 
 core_message_user_preferences ()
 Implements callback user_preferences, lists preferences that users are allowed to update directly.
 
 get_message_output_default_preferences ()
 Get messaging outputs default (site) preferences.
 
 get_message_processor ($type)
 Get an instance of the message_output class for one of the output plugins.
 
 get_message_processors ($ready=false, $reset=false, $resetonly=false)
 Get all message processors, validate corresponding plugin existance and system configuration.
 
 get_message_providers ()
 Get all message providers, validate their plugin existance and system configuration.
 
 message_format_contexturl ($message)
 Format a the context url and context url name of a message for display.
 
 message_format_message ($message, $format='', $keywords='', $class='other')
 Format a message for display in the message history.
 
 message_get_messages ($useridto, $useridfrom=0, $notifications=-1, $read=MESSAGE_GET_READ, $sort='mr.timecreated DESC', $limitfrom=0, $limitnum=0)
 Get messages sent or/and received by the specified users.
 
 message_get_providers_for_user ($userid)
 Returns the active providers for the user specified, based on capability.
 
 message_get_providers_from_db ($component)
 Gets the message providers that are in the database for this component.
 
 message_get_providers_from_file ($component)
 Loads the messages definitions for a component from file.
 
 message_handle_phpunit_redirection (\core\message\message $eventdata, string $table, stdClass $tabledata)
 Helper method containing the PHPUnit specific code, used to redirect and capture messages/notifications.
 
 message_output_fragment_processor_settings ($args=[])
 Handles displaying processor settings in a fragment.
 
 message_page_type_list (string $pagetype, ?context $parentcontext, ?context $currentcontext)
 Return a list of page types.
 
 message_post_message ($userfrom, $userto, $message, $format)
 Send a message from one user to another.
 
 message_processor_uninstall ($name)
 Uninstall a message processor.
 
 message_provider_uninstall ($component)
 Remove all message providers for particular component and corresponding settings.
 
 message_search_users ($courseids, $searchtext, $sort='', $exceptions='')
 Search through course users.
 
 message_send (\core\message\message $eventdata)
 Called when a message provider wants to send a message.
 
 message_set_default_message_preference ($component, $messagename, $fileprovider, $processorname='')
 Setting default messaging preferences for particular message provider.
 
 message_update_processors ($processorname)
 This function populates default message preferences for all existing providers when the new message processor is added.
 
 message_update_providers ($component='moodle')
 Updates the message_providers table with the current set of message providers.
 
 translate_message_default_setting ($plugindefault, $processorname)
 Translate message default settings from binary value to the array of string representing the settings to be stored.
 

Variables

global core_message\external::$CFG
 
 $handlers
 
const MESSAGE_DEFAULT_ENABLED 0x01
 
const MESSAGE_DEFAULT_LOGGEDIN 0x01
 Define contants for messaging default settings population.
 
const MESSAGE_DEFAULT_LOGGEDOFF 0x02
 
const MESSAGE_DEFAULT_MAX_POLL_IN_SECONDS 2 * MINSECS
 
const MESSAGE_DEFAULT_MIN_POLL_IN_SECONDS 10
 Set default values for polling.
 
const MESSAGE_DEFAULT_PERMITTED 'permitted'
 Set default value for default outputs permitted setting.
 
const MESSAGE_DEFAULT_TIMEOUT_POLL_IN_SECONDS 5 * MINSECS
 
const MESSAGE_DISALLOWED 0x04
 
const MESSAGE_FORCED 0x0c
 
const MESSAGE_GET_READ 1
 
const MESSAGE_GET_READ_AND_UNREAD 2
 
const MESSAGE_GET_UNREAD 0
 To get only read, unread or both messages or notifications.
 
const MESSAGE_HISTORY_ALL 1
 
const MESSAGE_PERMITTED 0x08
 
const MESSAGE_PERMITTED_MASK 0x0c
 
const MESSAGE_SEARCH_MAX_RESULTS 200
 
const MESSAGE_SHORTLENGTH 300
 
const MESSAGE_TYPE_MESSAGE 'message'
 
const MESSAGE_TYPE_NOTIFICATION 'notification'
 

Detailed Description

Function Documentation

◆ core_message_can_edit_message_profile()

core_message_can_edit_message_profile ( $user)

Checks if current user is allowed to edit messaging preferences of another user.

Parameters
stdClass$useruser whose preferences we are updating
Return values
bool

◆ core_message_standard_after_main_region_html()

core_message_standard_after_main_region_html ( )

Render the message drawer to be included in the top of the body of each page.

Return values
stringHTML

◆ core_message_user_preferences()

core_message_user_preferences ( )

Implements callback user_preferences, lists preferences that users are allowed to update directly.

Used in {

See also
core_user\fill_preferences_cache()}, see also {
useredit_update_user_preference()}
Return values
array

◆ get_message_output_default_preferences()

get_message_output_default_preferences ( )

Get messaging outputs default (site) preferences.

Return values
object\$processorsobject containing information on message processors

◆ get_message_processor()

get_message_processor ( $type)

Get an instance of the message_output class for one of the output plugins.

Parameters
string$typethe message output type. E.g. 'email' or 'jabber'.
Return values
message_outputmessage_output the requested class.

◆ get_message_processors()

get_message_processors ( $ready = false,
$reset = false,
$resetonly = false )

Get all message processors, validate corresponding plugin existance and system configuration.

Parameters
bool$readyonly return ready-to-use processors
bool$resetReset list of message processors (used in unit tests)
bool$resetonlyJust reset, then exit
Return values
mixed\$processorsarray of objects containing information on message processors

◆ get_message_providers()

get_message_providers ( )

Get all message providers, validate their plugin existance and system configuration.

Return values
mixed\$processorsarray of objects containing information on message processors

◆ message_format_contexturl()

message_format_contexturl ( $message)

Format a the context url and context url name of a message for display.

Parameters
object$messagethe message object
Return values
stringthe formatted string

◆ message_format_message()

message_format_message ( $message,
$format = '',
$keywords = '',
$class = 'other' )

Format a message for display in the message history.

Parameters
object$messagethe message object
string$formatoptional date format
string$keywordskeywords to highlight
string$classCSS class to apply to the div around the message
Return values
stringthe formatted message

◆ message_get_messages()

message_get_messages ( $useridto,
$useridfrom = 0,
$notifications = -1,
$read = MESSAGE_GET_READ,
$sort = 'mr.timecreated DESC',
$limitfrom = 0,
$limitnum = 0 )

Get messages sent or/and received by the specified users.

Please note that this function return deleted messages too. Besides, only individual conversation messages are returned to maintain backwards compatibility.

Parameters
int$useridtothe user id who received the message
int$useridfromthe user id who sent the message. -10 or -20 for no-reply or support user
int$notifications1 for retrieving notifications, 0 for messages, -1 for both
int$readEither MESSAGE_GET_READ, MESSAGE_GET_UNREAD or MESSAGE_GET_READ_AND_UNREAD.
string$sortthe column name to order by including optionally direction
int$limitfromlimit from
int$limitnumlimit num
Return values
external_description
Since
2.8

◆ message_get_providers_for_user()

message_get_providers_for_user ( $userid)

Returns the active providers for the user specified, based on capability.

Parameters
int$useridid of user
Return values
arrayAn array of message providers

◆ message_get_providers_from_db()

message_get_providers_from_db ( $component)

Gets the message providers that are in the database for this component.

This is an internal function used within messagelib.php

See also
message_update_providers()
Parameters
string$componentA moodle component like 'moodle', 'mod_forum', 'block_activity_results'
Return values
arrayAn array of message providers

◆ message_get_providers_from_file()

message_get_providers_from_file ( $component)

Loads the messages definitions for a component from file.

If no messages are defined for the component, return an empty array. This is an internal function used within messagelib.php

See also
message_update_providers()
message_update_processors()
Parameters
string$componentA moodle component like 'moodle', 'mod_forum', 'block_activity_results'
Return values
arrayAn array of message providers or empty array if not exists

◆ message_handle_phpunit_redirection()

message_handle_phpunit_redirection ( \core\message\message $eventdata,
string $table,
stdClass $tabledata )

Helper method containing the PHPUnit specific code, used to redirect and capture messages/notifications.

Parameters
core\message\message$eventdatathe message object
string$tablethe table to store the tabledata in, either messages or notifications.
stdClass$tabledatathe data to be stored when creating the message/notification.
Return values
intthe id of the stored message.

◆ message_output_fragment_processor_settings()

message_output_fragment_processor_settings ( $args = [])

Handles displaying processor settings in a fragment.

Parameters
array$args
Return values
bool|string
Exceptions
moodle_exception

◆ message_page_type_list()

message_page_type_list ( string $pagetype,
?context $parentcontext,
?context $currentcontext )

Return a list of page types.

Parameters
string$pagetypecurrent page type
context | null$parentcontextBlock's parent context
context | null$currentcontextCurrent context of block
Return values
array

◆ message_post_message()

message_post_message ( $userfrom,
$userto,
$message,
$format )

Send a message from one user to another.

Will be delivered according to the message recipients messaging preferences

Parameters
object$userfromthe message sender
object$usertothe message recipient
string$messagethe message
int$formatmessage format such as FORMAT_PLAIN or FORMAT_HTML
Return values
int|falsethe ID of the new message or false

◆ message_processor_uninstall()

message_processor_uninstall ( $name)

Uninstall a message processor.

Parameters
string$nameA message processor name like 'email', 'jabber'

◆ message_provider_uninstall()

message_provider_uninstall ( $component)

Remove all message providers for particular component and corresponding settings.

Parameters
string$componentA moodle component like 'moodle', 'mod_forum', 'block_activity_results'
Return values
void

◆ message_search_users()

message_search_users ( $courseids,
$searchtext,
$sort = '',
$exceptions = '' )

Search through course users.

If $courseids contains the site course then this function searches through all undeleted and confirmed users.

Parameters
int | array$courseidsCourse ID or array of course IDs.
string$searchtextthe text to search for.
string$sortthe column name to order by.
string | array$exceptionscomma separated list or array of user IDs to exclude.
Return values
arrayAn array of $USER records.

◆ message_send()

message_send ( \core\message\message $eventdata)

Called when a message provider wants to send a message.

This functions checks the message recipient's message processor configuration then sends the message to the configured processors

Required parameters of the $eventdata object: component string component name. must exist in message_providers name string message type name. must exist in message_providers userfrom object|int the user sending the message userto object|int the message recipient subject string the message subject fullmessage string the full message in a given format fullmessageformat int the format if the full message (FORMAT_MOODLE, FORMAT_HTML, ..) fullmessagehtml string the full version (the message processor will choose with one to use) smallmessage string the small version of the message

Optional parameters of the $eventdata object: notification bool should the message be considered as a notification rather than a personal message contexturl string if this is a notification then you can specify a url to view the event. For example the forum post the user is being notified of. contexturlname string the display text for contexturl

Note: processor failure will not reported as false return value in all scenarios, for example when it is called while a database transaction is open, earlier versions did not do it consistently either.

Parameters
core\message\message$eventdatainformation about the message (component, userfrom, userto, ...)
Return values
mixedthe integer ID of the new message or false if there was a problem (with submitted data or sending the message to the message processor)

◆ message_set_default_message_preference()

message_set_default_message_preference ( $component,
$messagename,
$fileprovider,
$processorname = '' )

Setting default messaging preferences for particular message provider.

Parameters
string$componentThe name of component (e.g. moodle, mod_forum, etc.)
string$messagenameThe name of message provider
array$fileproviderThe value of $messagename key in the array defined in plugin messages.php
string$processornameThe optional name of message processor

◆ message_update_processors()

message_update_processors ( $processorname)

This function populates default message preferences for all existing providers when the new message processor is added.

Parameters
string$processornameThe name of message processor plugin (e.g. 'email', 'jabber')
Exceptions
invalid_parameter_exceptionif $processorname does not exist in the database

◆ message_update_providers()

message_update_providers ( $component = 'moodle')

Updates the message_providers table with the current set of message providers.

Parameters
string$componentFor example 'moodle', 'mod_forum' or 'block_activity_results'
Return values
booleanTrue on success

◆ translate_message_default_setting()

translate_message_default_setting ( $plugindefault,
$processorname )

Translate message default settings from binary value to the array of string representing the settings to be stored.

Also validate the provided value and use default if it is malformed.

Todo
Remove usage of MESSAGE_DEFAULT_LOGGEDOFF on MDL-73284.
Parameters
int$plugindefaultDefault setting suggested by plugin
string$processornameThe name of processor
Return values
array\$settingsarray of strings in the order: $locked, $enabled.

Variable Documentation

◆ $handlers

$handlers
Initial value:
= array(
array(
'classname' => '\core\message\inbound\private_files_handler',
'defaultexpiration' => 0,
),
)

◆ MESSAGE_DEFAULT_LOGGEDIN

const MESSAGE_DEFAULT_LOGGEDIN 0x01

Define contants for messaging default settings population.

For unambiguity of plugin developer intentions we use 4-bit value (LSB numbering): bit 0 - whether to send message (MESSAGE_DEFAULT_ENABLED) bit 1 - Deprecated: whether to send message (MESSAGE_DEFAULT_LOGGEDOFF). Used to mean only when the user is logged off. bit 2..3 - messaging permission (MESSAGE_DISALLOWED|MESSAGE_PERMITTED|MESSAGE_FORCED)

MESSAGE_PERMITTED_MASK contains the mask we use to distinguish permission setting.

Deprecated
since Moodle 4.0. Use MESSAGE_DEFAULT_ENABLED instead.
Todo
Remove on MDL-73284.

◆ MESSAGE_DEFAULT_LOGGEDOFF

const MESSAGE_DEFAULT_LOGGEDOFF 0x02
Deprecated
since Moodle 4.0 MDL-73284. Use MESSAGE_DEFAULT_ENABLED instead.
Todo
Remove on MDL-73284.

◆ MESSAGE_DEFAULT_PERMITTED

const MESSAGE_DEFAULT_PERMITTED 'permitted'

Set default value for default outputs permitted setting.

Deprecated
since Moodle 4.0 MDL-73284.
Todo
Remove on MDL-73284.