5347f173b6116bb0e880690719c4b30eb4f30cce
[moodle.git] / lib / messagelib.php
1 <?php
2 // This file is part of Moodle - http://moodle.org/
3 //
4 // Moodle is free software: you can redistribute it and/or modify
5 // it under the terms of the GNU General Public License as published by
6 // the Free Software Foundation, either version 3 of the License, or
7 // (at your option) any later version.
8 //
9 // Moodle is distributed in the hope that it will be useful,
10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 // GNU General Public License for more details.
13 //
14 // You should have received a copy of the GNU General Public License
15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
17 /**
18  * Functions for interacting with the message system
19  *
20  * @package   core_message
21  * @copyright 2008 Luis Rodrigues and Martin Dougiamas
22  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
23  */
25 defined('MOODLE_INTERNAL') || die();
27 require_once(__DIR__ . '/../message/lib.php');
29 /**
30  * Called when a message provider wants to send a message.
31  * This functions checks the message recipient's message processor configuration then
32  * sends the message to the configured processors
33  *
34  * Required parameters of the $eventdata object:
35  *  component string component name. must exist in message_providers
36  *  name string message type name. must exist in message_providers
37  *  userfrom object|int the user sending the message
38  *  userto object|int the message recipient
39  *  subject string the message subject
40  *  fullmessage string the full message in a given format
41  *  fullmessageformat int the format if the full message (FORMAT_MOODLE, FORMAT_HTML, ..)
42  *  fullmessagehtml string the full version (the message processor will choose with one to use)
43  *  smallmessage string the small version of the message
44  *
45  * Optional parameters of the $eventdata object:
46  *  notification bool should the message be considered as a notification rather than a personal message
47  *  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.
48  *  contexturlname string the display text for contexturl
49  *
50  * Note: processor failure is is not reported as false return value,
51  *       earlier versions did not do it consistently either.
52  *
53  * @todo MDL-55449 Drop support for stdClass in Moodle 3.6
54  * @category message
55  * @param \core\message\message $eventdata information about the message (component, userfrom, userto, ...)
56  * @return mixed the integer ID of the new message or false if there was a problem with submitted data
57  */
58 function message_send($eventdata) {
59     global $CFG, $DB;
61     // TODO MDL-55449 Drop support for stdClass in Moodle 3.6.
62     if ($eventdata instanceof \stdClass) {
63         if (!isset($eventdata->courseid)) {
64             $eventdata->courseid = null;
65         }
67         debugging('eventdata as \stdClass is deprecated. Please use core\message\message instead.', DEBUG_DEVELOPER);
68     }
70     //new message ID to return
71     $messageid = false;
73     // Fetch default (site) preferences
74     $defaultpreferences = get_message_output_default_preferences();
75     $preferencebase = $eventdata->component.'_'.$eventdata->name;
76     // If message provider is disabled then don't do any processing.
77     if (!empty($defaultpreferences->{$preferencebase.'_disable'})) {
78         return $messageid;
79     }
81     // By default a message is a notification. Only personal/private messages aren't notifications.
82     if (!isset($eventdata->notification)) {
83         $eventdata->notification = 1;
84     }
86     if (!is_object($eventdata->userto)) {
87         $eventdata->userto = core_user::get_user($eventdata->userto);
88     }
89     if (!is_object($eventdata->userfrom)) {
90         $eventdata->userfrom = core_user::get_user($eventdata->userfrom);
91     }
92     if (!$eventdata->userto) {
93         debugging('Attempt to send msg to unknown user', DEBUG_NORMAL);
94         return false;
95     }
96     if (!$eventdata->userfrom) {
97         debugging('Attempt to send msg from unknown user', DEBUG_NORMAL);
98         return false;
99     }
101     // Verify all necessary data fields are present.
102     if (!isset($eventdata->userto->auth) or !isset($eventdata->userto->suspended)
103             or !isset($eventdata->userto->deleted) or !isset($eventdata->userto->emailstop)) {
105         debugging('Necessary properties missing in userto object, fetching full record', DEBUG_DEVELOPER);
106         $eventdata->userto = core_user::get_user($eventdata->userto->id);
107     }
109     $usertoisrealuser = (core_user::is_real_user($eventdata->userto->id) != false);
110     // If recipient is internal user (noreply user), and emailstop is set then don't send any msg.
111     if (!$usertoisrealuser && !empty($eventdata->userto->emailstop)) {
112         debugging('Attempt to send msg to internal (noreply) user', DEBUG_NORMAL);
113         return false;
114     }
116     //after how long inactive should the user be considered logged off?
117     if (isset($CFG->block_online_users_timetosee)) {
118         $timetoshowusers = $CFG->block_online_users_timetosee * 60;
119     } else {
120         $timetoshowusers = 300;//5 minutes
121     }
123     // Work out if the user is logged in or not
124     if (!empty($eventdata->userto->lastaccess) && (time()-$timetoshowusers) < $eventdata->userto->lastaccess) {
125         $userstate = 'loggedin';
126     } else {
127         $userstate = 'loggedoff';
128     }
130     // Create the message object
131     $savemessage = new stdClass();
132     $savemessage->courseid          = $eventdata->courseid;
133     $savemessage->useridfrom        = $eventdata->userfrom->id;
134     $savemessage->useridto          = $eventdata->userto->id;
135     $savemessage->subject           = $eventdata->subject;
136     $savemessage->fullmessage       = $eventdata->fullmessage;
137     $savemessage->fullmessageformat = $eventdata->fullmessageformat;
138     $savemessage->fullmessagehtml   = $eventdata->fullmessagehtml;
139     $savemessage->smallmessage      = $eventdata->smallmessage;
140     $savemessage->notification      = $eventdata->notification;
141     $savemessage->eventtype         = $eventdata->name;
142     $savemessage->component         = $eventdata->component;
144     if (!empty($eventdata->contexturl)) {
145         $savemessage->contexturl = (string)$eventdata->contexturl;
146     } else {
147         $savemessage->contexturl = null;
148     }
150     if (!empty($eventdata->contexturlname)) {
151         $savemessage->contexturlname = (string)$eventdata->contexturlname;
152     } else {
153         $savemessage->contexturlname = null;
154     }
156     $savemessage->timecreated = time();
158     if (PHPUNIT_TEST and class_exists('phpunit_util')) {
159         // Add some more tests to make sure the normal code can actually work.
160         $componentdir = core_component::get_component_directory($eventdata->component);
161         if (!$componentdir or !is_dir($componentdir)) {
162             throw new coding_exception('Invalid component specified in message-send(): '.$eventdata->component);
163         }
164         if (!file_exists("$componentdir/db/messages.php")) {
165             throw new coding_exception("$eventdata->component does not contain db/messages.php necessary for message_send()");
166         }
167         $messageproviders = null;
168         include("$componentdir/db/messages.php");
169         if (!isset($messageproviders[$eventdata->name])) {
170             throw new coding_exception("Missing messaging defaults for event '$eventdata->name' in '$eventdata->component' messages.php file");
171         }
172         unset($componentdir);
173         unset($messageproviders);
174         // Now ask phpunit if it wants to catch this message.
175         if (phpunit_util::is_redirecting_messages()) {
176             $savemessage->timeread = time();
177             $messageid = $DB->insert_record('message_read', $savemessage);
178             $message = $DB->get_record('message_read', array('id'=>$messageid));
179             phpunit_util::message_sent($message);
180             return $messageid;
181         }
182     }
184     // Fetch enabled processors
185     $processors = get_message_processors(true);
187     // Preset variables
188     $processorlist = array();
189     // Fill in the array of processors to be used based on default and user preferences
190     foreach ($processors as $processor) {
191         // Skip adding processors for internal user, if processor doesn't support sending message to internal user.
192         if (!$usertoisrealuser && !$processor->object->can_send_to_any_users()) {
193             continue;
194         }
196         // First find out permissions
197         $defaultpreference = $processor->name.'_provider_'.$preferencebase.'_permitted';
198         if (isset($defaultpreferences->{$defaultpreference})) {
199             $permitted = $defaultpreferences->{$defaultpreference};
200         } else {
201             // MDL-25114 They supplied an $eventdata->component $eventdata->name combination which doesn't
202             // exist in the message_provider table (thus there is no default settings for them).
203             $preferrormsg = "Could not load preference $defaultpreference. Make sure the component and name you supplied
204                     to message_send() are valid.";
205             throw new coding_exception($preferrormsg);
206         }
208         // Find out if user has configured this output
209         // Some processors cannot function without settings from the user
210         $userisconfigured = $processor->object->is_user_configured($eventdata->userto);
212         // DEBUG: notify if we are forcing unconfigured output
213         if ($permitted == 'forced' && !$userisconfigured) {
214             debugging('Attempt to force message delivery to user who has "'.$processor->name.'" output unconfigured', DEBUG_NORMAL);
215         }
217         // Populate the list of processors we will be using
218         if ($permitted == 'forced' && $userisconfigured) {
219             // An admin is forcing users to use this message processor. Use this processor unconditionally.
220             $processorlist[] = $processor->name;
221         } else if ($permitted == 'permitted' && $userisconfigured && !$eventdata->userto->emailstop) {
222             // User has not disabled notifications
223             // See if user set any notification preferences, otherwise use site default ones
224             $userpreferencename = 'message_provider_'.$preferencebase.'_'.$userstate;
225             if ($userpreference = get_user_preferences($userpreferencename, null, $eventdata->userto)) {
226                 if (in_array($processor->name, explode(',', $userpreference))) {
227                     $processorlist[] = $processor->name;
228                 }
229             } else if (isset($defaultpreferences->{$userpreferencename})) {
230                 if (in_array($processor->name, explode(',', $defaultpreferences->{$userpreferencename}))) {
231                     $processorlist[] = $processor->name;
232                 }
233             }
234         }
235     }
237     // Only cache messages, not notifications.
238     if (empty($savemessage->notification)) {
239         // Cache the timecreated value of the last message between these two users.
240         $cache = cache::make('core', 'message_time_last_message_between_users');
241         $key = \core_message\helper::get_last_message_time_created_cache_key($savemessage->useridfrom,
242             $savemessage->useridto);
243         $cache->set($key, $savemessage->timecreated);
244     }
246     // Store unread message just in case we get a fatal error any time later.
247     $savemessage->id = $DB->insert_record('message', $savemessage);
248     $eventdata->savedmessageid = $savemessage->id;
250     // Let the manager do the sending or buffering when db transaction in progress.
251     return \core\message\manager::send_message($eventdata, $savemessage, $processorlist);
255 /**
256  * Updates the message_providers table with the current set of message providers
257  *
258  * @param string $component For example 'moodle', 'mod_forum' or 'block_quiz_results'
259  * @return boolean True on success
260  */
261 function message_update_providers($component='moodle') {
262     global $DB;
264     // load message providers from files
265     $fileproviders = message_get_providers_from_file($component);
267     // load message providers from the database
268     $dbproviders = message_get_providers_from_db($component);
270     foreach ($fileproviders as $messagename => $fileprovider) {
272         if (!empty($dbproviders[$messagename])) {   // Already exists in the database
273             // check if capability has changed
274             if ($dbproviders[$messagename]->capability == $fileprovider['capability']) {  // Same, so ignore
275                 // exact same message provider already present in db, ignore this entry
276                 unset($dbproviders[$messagename]);
277                 continue;
279             } else {                                // Update existing one
280                 $provider = new stdClass();
281                 $provider->id         = $dbproviders[$messagename]->id;
282                 $provider->capability = $fileprovider['capability'];
283                 $DB->update_record('message_providers', $provider);
284                 unset($dbproviders[$messagename]);
285                 continue;
286             }
288         } else {             // New message provider, add it
290             $provider = new stdClass();
291             $provider->name       = $messagename;
292             $provider->component  = $component;
293             $provider->capability = $fileprovider['capability'];
295             $transaction = $DB->start_delegated_transaction();
296             $DB->insert_record('message_providers', $provider);
297             message_set_default_message_preference($component, $messagename, $fileprovider);
298             $transaction->allow_commit();
299         }
300     }
302     foreach ($dbproviders as $dbprovider) {  // Delete old ones
303         $DB->delete_records('message_providers', array('id' => $dbprovider->id));
304         $DB->delete_records_select('config_plugins', "plugin = 'message' AND ".$DB->sql_like('name', '?', false), array("%_provider_{$component}_{$dbprovider->name}_%"));
305         $DB->delete_records_select('user_preferences', $DB->sql_like('name', '?', false), array("message_provider_{$component}_{$dbprovider->name}_%"));
306         cache_helper::invalidate_by_definition('core', 'config', array(), 'message');
307     }
309     return true;
312 /**
313  * This function populates default message preferences for all existing providers
314  * when the new message processor is added.
315  *
316  * @param string $processorname The name of message processor plugin (e.g. 'email', 'jabber')
317  * @throws invalid_parameter_exception if $processorname does not exist in the database
318  */
319 function message_update_processors($processorname) {
320     global $DB;
322     // validate if our processor exists
323     $processor = $DB->get_records('message_processors', array('name' => $processorname));
324     if (empty($processor)) {
325         throw new invalid_parameter_exception();
326     }
328     $providers = $DB->get_records_sql('SELECT DISTINCT component FROM {message_providers}');
330     $transaction = $DB->start_delegated_transaction();
331     foreach ($providers as $provider) {
332         // load message providers from files
333         $fileproviders = message_get_providers_from_file($provider->component);
334         foreach ($fileproviders as $messagename => $fileprovider) {
335             message_set_default_message_preference($provider->component, $messagename, $fileprovider, $processorname);
336         }
337     }
338     $transaction->allow_commit();
341 /**
342  * Setting default messaging preferences for particular message provider
343  *
344  * @param  string $component   The name of component (e.g. moodle, mod_forum, etc.)
345  * @param  string $messagename The name of message provider
346  * @param  array  $fileprovider The value of $messagename key in the array defined in plugin messages.php
347  * @param  string $processorname The optional name of message processor
348  */
349 function message_set_default_message_preference($component, $messagename, $fileprovider, $processorname='') {
350     global $DB;
352     // Fetch message processors
353     $condition = null;
354     // If we need to process a particular processor, set the select condition
355     if (!empty($processorname)) {
356        $condition = array('name' => $processorname);
357     }
358     $processors = $DB->get_records('message_processors', $condition);
360     // load default messaging preferences
361     $defaultpreferences = get_message_output_default_preferences();
363     // Setting default preference
364     $componentproviderbase = $component.'_'.$messagename;
365     $loggedinpref = array();
366     $loggedoffpref = array();
367     // set 'permitted' preference first for each messaging processor
368     foreach ($processors as $processor) {
369         $preferencename = $processor->name.'_provider_'.$componentproviderbase.'_permitted';
370         // if we do not have this setting yet, set it
371         if (!isset($defaultpreferences->{$preferencename})) {
372             // determine plugin default settings
373             $plugindefault = 0;
374             if (isset($fileprovider['defaults'][$processor->name])) {
375                 $plugindefault = $fileprovider['defaults'][$processor->name];
376             }
377             // get string values of the settings
378             list($permitted, $loggedin, $loggedoff) = translate_message_default_setting($plugindefault, $processor->name);
379             // store default preferences for current processor
380             set_config($preferencename, $permitted, 'message');
381             // save loggedin/loggedoff settings
382             if ($loggedin) {
383                 $loggedinpref[] = $processor->name;
384             }
385             if ($loggedoff) {
386                 $loggedoffpref[] = $processor->name;
387             }
388         }
389     }
390     // now set loggedin/loggedoff preferences
391     if (!empty($loggedinpref)) {
392         $preferencename = 'message_provider_'.$componentproviderbase.'_loggedin';
393         if (isset($defaultpreferences->{$preferencename})) {
394             // We have the default preferences for this message provider, which
395             // likely means that we have been adding a new processor. Add defaults
396             // to exisitng preferences.
397             $loggedinpref = array_merge($loggedinpref, explode(',', $defaultpreferences->{$preferencename}));
398         }
399         set_config($preferencename, join(',', $loggedinpref), 'message');
400     }
401     if (!empty($loggedoffpref)) {
402         $preferencename = 'message_provider_'.$componentproviderbase.'_loggedoff';
403         if (isset($defaultpreferences->{$preferencename})) {
404             // We have the default preferences for this message provider, which
405             // likely means that we have been adding a new processor. Add defaults
406             // to exisitng preferences.
407             $loggedoffpref = array_merge($loggedoffpref, explode(',', $defaultpreferences->{$preferencename}));
408         }
409         set_config($preferencename, join(',', $loggedoffpref), 'message');
410     }
413 /**
414  * Returns the active providers for the user specified, based on capability
415  *
416  * @param int $userid id of user
417  * @return array An array of message providers
418  */
419 function message_get_providers_for_user($userid) {
420     global $DB, $CFG;
422     $providers = get_message_providers();
424     // Ensure user is not allowed to configure instantmessage if it is globally disabled.
425     if (!$CFG->messaging) {
426         foreach ($providers as $providerid => $provider) {
427             if ($provider->name == 'instantmessage') {
428                 unset($providers[$providerid]);
429                 break;
430             }
431         }
432     }
434     // If the component is an enrolment plugin, check it is enabled
435     foreach ($providers as $providerid => $provider) {
436         list($type, $name) = core_component::normalize_component($provider->component);
437         if ($type == 'enrol' && !enrol_is_enabled($name)) {
438             unset($providers[$providerid]);
439         }
440     }
442     // Now we need to check capabilities. We need to eliminate the providers
443     // where the user does not have the corresponding capability anywhere.
444     // Here we deal with the common simple case of the user having the
445     // capability in the system context. That handles $CFG->defaultuserroleid.
446     // For the remaining providers/capabilities, we need to do a more complex
447     // query involving all overrides everywhere.
448     $unsureproviders = array();
449     $unsurecapabilities = array();
450     $systemcontext = context_system::instance();
451     foreach ($providers as $providerid => $provider) {
452         if (empty($provider->capability) || has_capability($provider->capability, $systemcontext, $userid)) {
453             // The provider is relevant to this user.
454             continue;
455         }
457         $unsureproviders[$providerid] = $provider;
458         $unsurecapabilities[$provider->capability] = 1;
459         unset($providers[$providerid]);
460     }
462     if (empty($unsureproviders)) {
463         // More complex checks are not required.
464         return $providers;
465     }
467     // Now check the unsure capabilities.
468     list($capcondition, $params) = $DB->get_in_or_equal(
469             array_keys($unsurecapabilities), SQL_PARAMS_NAMED);
470     $params['userid'] = $userid;
472     $sql = "SELECT DISTINCT rc.capability, 1
474               FROM {role_assignments} ra
475               JOIN {context} actx ON actx.id = ra.contextid
476               JOIN {role_capabilities} rc ON rc.roleid = ra.roleid
477               JOIN {context} cctx ON cctx.id = rc.contextid
479              WHERE ra.userid = :userid
480                AND rc.capability $capcondition
481                AND rc.permission > 0
482                AND (".$DB->sql_concat('actx.path', "'/'")." LIKE ".$DB->sql_concat('cctx.path', "'/%'").
483                " OR ".$DB->sql_concat('cctx.path', "'/'")." LIKE ".$DB->sql_concat('actx.path', "'/%'").")";
485     if (!empty($CFG->defaultfrontpageroleid)) {
486         $frontpagecontext = context_course::instance(SITEID);
488         list($capcondition2, $params2) = $DB->get_in_or_equal(
489                 array_keys($unsurecapabilities), SQL_PARAMS_NAMED);
490         $params = array_merge($params, $params2);
491         $params['frontpageroleid'] = $CFG->defaultfrontpageroleid;
492         $params['frontpagepathpattern'] = $frontpagecontext->path . '/';
494         $sql .= "
495              UNION
497             SELECT DISTINCT rc.capability, 1
499               FROM {role_capabilities} rc
500               JOIN {context} cctx ON cctx.id = rc.contextid
502              WHERE rc.roleid = :frontpageroleid
503                AND rc.capability $capcondition2
504                AND rc.permission > 0
505                AND ".$DB->sql_concat('cctx.path', "'/'")." LIKE :frontpagepathpattern";
506     }
508     $relevantcapabilities = $DB->get_records_sql_menu($sql, $params);
510     // Add back any providers based on the detailed capability check.
511     foreach ($unsureproviders as $providerid => $provider) {
512         if (array_key_exists($provider->capability, $relevantcapabilities)) {
513             $providers[$providerid] = $provider;
514         }
515     }
517     return $providers;
520 /**
521  * Gets the message providers that are in the database for this component.
522  *
523  * This is an internal function used within messagelib.php
524  *
525  * @see message_update_providers()
526  * @param string $component A moodle component like 'moodle', 'mod_forum', 'block_quiz_results'
527  * @return array An array of message providers
528  */
529 function message_get_providers_from_db($component) {
530     global $DB;
532     return $DB->get_records('message_providers', array('component'=>$component), '', 'name, id, component, capability');  // Name is unique per component
535 /**
536  * Loads the messages definitions for a component from file
537  *
538  * If no messages are defined for the component, return an empty array.
539  * This is an internal function used within messagelib.php
540  *
541  * @see message_update_providers()
542  * @see message_update_processors()
543  * @param string $component A moodle component like 'moodle', 'mod_forum', 'block_quiz_results'
544  * @return array An array of message providers or empty array if not exists
545  */
546 function message_get_providers_from_file($component) {
547     $defpath = core_component::get_component_directory($component).'/db/messages.php';
549     $messageproviders = array();
551     if (file_exists($defpath)) {
552         require($defpath);
553     }
555     foreach ($messageproviders as $name => $messageprovider) {   // Fix up missing values if required
556         if (empty($messageprovider['capability'])) {
557             $messageproviders[$name]['capability'] = NULL;
558         }
559         if (empty($messageprovider['defaults'])) {
560             $messageproviders[$name]['defaults'] = array();
561         }
562     }
564     return $messageproviders;
567 /**
568  * Remove all message providers for particular component and corresponding settings
569  *
570  * @param string $component A moodle component like 'moodle', 'mod_forum', 'block_quiz_results'
571  * @return void
572  */
573 function message_provider_uninstall($component) {
574     global $DB;
576     $transaction = $DB->start_delegated_transaction();
577     $DB->delete_records('message_providers', array('component' => $component));
578     $DB->delete_records_select('config_plugins', "plugin = 'message' AND ".$DB->sql_like('name', '?', false), array("%_provider_{$component}_%"));
579     $DB->delete_records_select('user_preferences', $DB->sql_like('name', '?', false), array("message_provider_{$component}_%"));
580     $transaction->allow_commit();
581     // Purge all messaging settings from the caches. They are stored by plugin so we have to clear all message settings.
582     cache_helper::invalidate_by_definition('core', 'config', array(), 'message');
585 /**
586  * Uninstall a message processor
587  *
588  * @param string $name A message processor name like 'email', 'jabber'
589  */
590 function message_processor_uninstall($name) {
591     global $DB;
593     $transaction = $DB->start_delegated_transaction();
594     $DB->delete_records('message_processors', array('name' => $name));
595     $DB->delete_records_select('config_plugins', "plugin = ?", array("message_{$name}"));
596     // delete permission preferences only, we do not care about loggedin/loggedoff
597     // defaults, they will be removed on the next attempt to update the preferences
598     $DB->delete_records_select('config_plugins', "plugin = 'message' AND ".$DB->sql_like('name', '?', false), array("{$name}_provider_%"));
599     $transaction->allow_commit();
600     // Purge all messaging settings from the caches. They are stored by plugin so we have to clear all message settings.
601     cache_helper::invalidate_by_definition('core', 'config', array(), array('message', "message_{$name}"));