MDL-30545 - messagelib: use $DB->sql_concat()
[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(dirname(dirname(__FILE__)) . '/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  * @category message
51  * @param object $eventdata information about the message (component, userfrom, userto, ...)
52  * @return mixed the integer ID of the new message or false if there was a problem with a processor
53  */
54 function message_send($eventdata) {
55     global $CFG, $DB;
57     //new message ID to return
58     $messageid = false;
60     //TODO: we need to solve problems with database transactions here somehow, for now we just prevent transactions - sorry
61     $DB->transactions_forbidden();
63     if (is_number($eventdata->userto)) {
64         $eventdata->userto = $DB->get_record('user', array('id' => $eventdata->userto));
65     }
66     if (is_int($eventdata->userfrom)) {
67         $eventdata->userfrom = $DB->get_record('user', array('id' => $eventdata->userfrom));
68     }
69     if (!isset($eventdata->userto->auth) or !isset($eventdata->userto->suspended) or !isset($eventdata->userto->deleted)) {
70         $eventdata->userto = $DB->get_record('user', array('id' => $eventdata->userto->id));
71     }
73     //after how long inactive should the user be considered logged off?
74     if (isset($CFG->block_online_users_timetosee)) {
75         $timetoshowusers = $CFG->block_online_users_timetosee * 60;
76     } else {
77         $timetoshowusers = 300;//5 minutes
78     }
80     // Work out if the user is logged in or not
81     if (!empty($eventdata->userto->lastaccess) && (time()-$timetoshowusers) < $eventdata->userto->lastaccess) {
82         $userstate = 'loggedin';
83     } else {
84         $userstate = 'loggedoff';
85     }
87     // Create the message object
88     $savemessage = new stdClass();
89     $savemessage->useridfrom        = $eventdata->userfrom->id;
90     $savemessage->useridto          = $eventdata->userto->id;
91     $savemessage->subject           = $eventdata->subject;
92     $savemessage->fullmessage       = $eventdata->fullmessage;
93     $savemessage->fullmessageformat = $eventdata->fullmessageformat;
94     $savemessage->fullmessagehtml   = $eventdata->fullmessagehtml;
95     $savemessage->smallmessage      = $eventdata->smallmessage;
97     if (!empty($eventdata->notification)) {
98         $savemessage->notification = $eventdata->notification;
99     } else {
100         $savemessage->notification = 0;
101     }
103     if (!empty($eventdata->contexturl)) {
104         $savemessage->contexturl = $eventdata->contexturl;
105     } else {
106         $savemessage->contexturl = null;
107     }
109     if (!empty($eventdata->contexturlname)) {
110         $savemessage->contexturlname = $eventdata->contexturlname;
111     } else {
112         $savemessage->contexturlname = null;
113     }
115     $savemessage->timecreated = time();
117     // Fetch enabled processors
118     $processors = get_message_processors(true);
119     // Fetch default (site) preferences
120     $defaultpreferences = get_message_output_default_preferences();
122     // Preset variables
123     $processorlist = array();
124     $preferencebase = $eventdata->component.'_'.$eventdata->name;
125     // Fill in the array of processors to be used based on default and user preferences
126     foreach ($processors as $processor) {
127         // First find out permissions
128         $defaultpreference = $processor->name.'_provider_'.$preferencebase.'_permitted';
129         if (isset($defaultpreferences->{$defaultpreference})) {
130             $permitted = $defaultpreferences->{$defaultpreference};
131         } else {
132             //MDL-25114 They supplied an $eventdata->component $eventdata->name combination which doesn't
133             //exist in the message_provider table (thus there is no default settings for them)
134             $preferrormsg = get_string('couldnotfindpreference', 'message', $defaultpreference);
135             throw new coding_exception($preferrormsg,'blah');
136         }
138         // Find out if user has configured this output
139         // Some processors cannot function without settings from the user
140         $userisconfigured = $processor->object->is_user_configured($eventdata->userto);
142         // DEBUG: notify if we are forcing unconfigured output
143         if ($permitted == 'forced' && !$userisconfigured) {
144             debugging('Attempt to force message delivery to user who has "'.$processor->name.'" output unconfigured', DEBUG_NORMAL);
145         }
147         // Warn developers that necessary data is missing regardless of how the processors are configured
148         if (!isset($eventdata->userto->emailstop)) {
149             debugging('userto->emailstop is not set. Retrieving it from the user table');
150             $eventdata->userto->emailstop = $DB->get_field('user', 'emailstop', array('id'=>$eventdata->userto->id));
151         }
153         // Populate the list of processors we will be using
154         if ($permitted == 'forced' && $userisconfigured) {
155             // An admin is forcing users to use this message processor. Use this processor unconditionally.
156             $processorlist[] = $processor->name;
157         } else if ($permitted == 'permitted' && $userisconfigured && !$eventdata->userto->emailstop) {
158             // User has not disabled notifications
159             // See if user set any notification preferences, otherwise use site default ones
160             $userpreferencename = 'message_provider_'.$preferencebase.'_'.$userstate;
161             if ($userpreference = get_user_preferences($userpreferencename, null, $eventdata->userto->id)) {
162                 if (in_array($processor->name, explode(',', $userpreference))) {
163                     $processorlist[] = $processor->name;
164                 }
165             } else if (isset($defaultpreferences->{$userpreferencename})) {
166                 if (in_array($processor->name, explode(',', $defaultpreferences->{$userpreferencename}))) {
167                     $processorlist[] = $processor->name;
168                 }
169             }
170         }
171     }
173     if (empty($processorlist) && $savemessage->notification) {
174         //if they have deselected all processors and its a notification mark it read. The user doesnt want to be bothered
175         $savemessage->timeread = time();
176         $messageid = $DB->insert_record('message_read', $savemessage);
177     } else {                        // Process the message
178         // Store unread message just in case we can not send it
179         $messageid = $savemessage->id = $DB->insert_record('message', $savemessage);
180         $eventdata->savedmessageid = $savemessage->id;
182         // Try to deliver the message to each processor
183         if (!empty($processorlist)) {
184             foreach ($processorlist as $procname) {
185                 if (!$processors[$procname]->object->send_message($eventdata)) {
186                     debugging('Error calling message processor '.$procname);
187                     $messageid = false;
188                 }
189             }
191             //if messaging is disabled and they previously had forum notifications handled by the popup processor
192             //or any processor that puts a row in message_working then the notification will remain forever
193             //unread. To prevent this mark the message read if messaging is disabled
194             if (empty($CFG->messaging)) {
195                 require_once($CFG->dirroot.'/message/lib.php');
196                 $messageid = message_mark_message_read($savemessage, time());
197             } else if ( $DB->count_records('message_working', array('unreadmessageid' => $savemessage->id)) == 0){
198                 //if there is no more processors that want to process this we can move message to message_read
199                 require_once($CFG->dirroot.'/message/lib.php');
200                 $messageid = message_mark_message_read($savemessage, time(), true);
201             }
202         }
203     }
205     return $messageid;
209 /**
210  * Updates the message_providers table with the current set of message providers
211  *
212  * @param string $component For example 'moodle', 'mod_forum' or 'block_quiz_results'
213  * @return boolean True on success
214  */
215 function message_update_providers($component='moodle') {
216     global $DB;
218     // load message providers from files
219     $fileproviders = message_get_providers_from_file($component);
221     // load message providers from the database
222     $dbproviders = message_get_providers_from_db($component);
224     foreach ($fileproviders as $messagename => $fileprovider) {
226         if (!empty($dbproviders[$messagename])) {   // Already exists in the database
227             // check if capability has changed
228             if ($dbproviders[$messagename]->capability == $fileprovider['capability']) {  // Same, so ignore
229                 // exact same message provider already present in db, ignore this entry
230                 unset($dbproviders[$messagename]);
231                 continue;
233             } else {                                // Update existing one
234                 $provider = new stdClass();
235                 $provider->id         = $dbproviders[$messagename]->id;
236                 $provider->capability = $fileprovider['capability'];
237                 $DB->update_record('message_providers', $provider);
238                 unset($dbproviders[$messagename]);
239                 continue;
240             }
242         } else {             // New message provider, add it
244             $provider = new stdClass();
245             $provider->name       = $messagename;
246             $provider->component  = $component;
247             $provider->capability = $fileprovider['capability'];
249             $transaction = $DB->start_delegated_transaction();
250             $DB->insert_record('message_providers', $provider);
251             message_set_default_message_preference($component, $messagename, $fileprovider);
252             $transaction->allow_commit();
253         }
254     }
256     foreach ($dbproviders as $dbprovider) {  // Delete old ones
257         $DB->delete_records('message_providers', array('id' => $dbprovider->id));
258         $DB->delete_records_select('config_plugins', "plugin = 'message' AND ".$DB->sql_like('name', '?', false), array("%_provider_{$component}_{$dbprovider->name}_%"));
259         $DB->delete_records_select('user_preferences', $DB->sql_like('name', '?', false), array("message_provider_{$component}_{$dbprovider->name}_%"));
260     }
262     return true;
265 /**
266  * This function populates default message preferences for all existing providers
267  * when the new message processor is added.
268  *
269  * @param string $processorname The name of message processor plugin (e.g. 'email', 'jabber')
270  * @throws invalid_parameter_exception if $processorname does not exist in the database
271  */
272 function message_update_processors($processorname) {
273     global $DB;
275     // validate if our processor exists
276     $processor = $DB->get_records('message_processors', array('name' => $processorname));
277     if (empty($processor)) {
278         throw new invalid_parameter_exception();
279     }
281     $providers = $DB->get_records_sql('SELECT DISTINCT component FROM {message_providers}');
283     $transaction = $DB->start_delegated_transaction();
284     foreach ($providers as $provider) {
285         // load message providers from files
286         $fileproviders = message_get_providers_from_file($provider->component);
287         foreach ($fileproviders as $messagename => $fileprovider) {
288             message_set_default_message_preference($provider->component, $messagename, $fileprovider, $processorname);
289         }
290     }
291     $transaction->allow_commit();
294 /**
295  * Setting default messaging preferences for particular message provider
296  *
297  * @param  string $component   The name of component (e.g. moodle, mod_forum, etc.)
298  * @param  string $messagename The name of message provider
299  * @param  array  $fileprovider The value of $messagename key in the array defined in plugin messages.php
300  * @param  string $processorname The optional name of message processor
301  */
302 function message_set_default_message_preference($component, $messagename, $fileprovider, $processorname='') {
303     global $DB;
305     // Fetch message processors
306     $condition = null;
307     // If we need to process a particular processor, set the select condition
308     if (!empty($processorname)) {
309        $condition = array('name' => $processorname);
310     }
311     $processors = $DB->get_records('message_processors', $condition);
313     // load default messaging preferences
314     $defaultpreferences = get_message_output_default_preferences();
316     // Setting default preference
317     $componentproviderbase = $component.'_'.$messagename;
318     $loggedinpref = array();
319     $loggedoffpref = array();
320     // set 'permitted' preference first for each messaging processor
321     foreach ($processors as $processor) {
322         $preferencename = $processor->name.'_provider_'.$componentproviderbase.'_permitted';
323         // if we do not have this setting yet, set it
324         if (!isset($defaultpreferences->{$preferencename})) {
325             // determine plugin default settings
326             $plugindefault = 0;
327             if (isset($fileprovider['defaults'][$processor->name])) {
328                 $plugindefault = $fileprovider['defaults'][$processor->name];
329             }
330             // get string values of the settings
331             list($permitted, $loggedin, $loggedoff) = translate_message_default_setting($plugindefault, $processor->name);
332             // store default preferences for current processor
333             set_config($preferencename, $permitted, 'message');
334             // save loggedin/loggedoff settings
335             if ($loggedin) {
336                 $loggedinpref[] = $processor->name;
337             }
338             if ($loggedoff) {
339                 $loggedoffpref[] = $processor->name;
340             }
341         }
342     }
343     // now set loggedin/loggedoff preferences
344     if (!empty($loggedinpref)) {
345         $preferencename = 'message_provider_'.$componentproviderbase.'_loggedin';
346         if (isset($defaultpreferences->{$preferencename})) {
347             // We have the default preferences for this message provider, which
348             // likely means that we have been adding a new processor. Add defaults
349             // to exisitng preferences.
350             $loggedinpref = array_merge($loggedinpref, explode(',', $defaultpreferences->{$preferencename}));
351         }
352         set_config($preferencename, join(',', $loggedinpref), 'message');
353     }
354     if (!empty($loggedoffpref)) {
355         $preferencename = 'message_provider_'.$componentproviderbase.'_loggedoff';
356         if (isset($defaultpreferences->{$preferencename})) {
357             // We have the default preferences for this message provider, which
358             // likely means that we have been adding a new processor. Add defaults
359             // to exisitng preferences.
360             $loggedoffpref = array_merge($loggedoffpref, explode(',', $defaultpreferences->{$preferencename}));
361         }
362         set_config($preferencename, join(',', $loggedoffpref), 'message');
363     }
366 /**
367  * This function has been deprecated please use {@link message_get_providers_for_user()} instead.
368  *
369  * Returns the active providers for the current user, based on capability
370  *
371  * @see message_get_providers_for_user()
372  * @deprecated since 2.1
373  * @todo Remove in 2.2 (MDL-31031)
374  * @return array An array of message providers
375  */
376 function message_get_my_providers() {
377     global $USER;
378     return message_get_providers_for_user($USER->id);
381 /**
382  * Returns the active providers for the user specified, based on capability
383  *
384  * @param int $userid id of user
385  * @return array An array of message providers
386  */
387 function message_get_providers_for_user($userid) {
388     global $DB, $CFG;
390     $providers = get_message_providers();
392     // Ensure user is not allowed to configure instantmessage if it is globally disabled.
393     if (!$CFG->messaging) {
394         foreach ($providers as $providerid => $provider) {
395             if ($provider->name == 'instantmessage') {
396                 unset($providers[$providerid]);
397                 break;
398             }
399         }
400     }
402     // If the component is an enrolment plugin, check it is enabled
403     foreach ($providers as $providerid => $provider) {
404         list($type, $name) = normalize_component($provider->component);
405         if ($type == 'enrol' && !enrol_is_enabled($name)) {
406             unset($providers[$providerid]);
407         }
408     }
410     // Now we need to check capabilities. We need to eliminate the providers
411     // where the user does not have the corresponding capability anywhere.
412     // Here we deal with the common simple case of the user having the
413     // capability in the system context. That handles $CFG->defaultuserroleid.
414     // For the remaining providers/capabilities, we need to do a more complex
415     // query involving all overrides everywhere.
416     $unsureproviders = array();
417     $unsurecapabilities = array();
418     $systemcontext = context_system::instance();
419     foreach ($providers as $providerid => $provider) {
420         if (empty($provider->capability) || has_capability($provider->capability, $systemcontext, $userid)) {
421             // The provider is relevant to this user.
422             continue;
423         }
425         $unsureproviders[$providerid] = $provider;
426         $unsurecapabilities[$provider->capability] = 1;
427         unset($providers[$providerid]);
428     }
430     if (empty($unsureproviders)) {
431         // More complex checks are not required.
432         return $providers;
433     }
435     // Now check the unsure capabilities.
436     list($capcondition, $params) = $DB->get_in_or_equal(
437             array_keys($unsurecapabilities), SQL_PARAMS_NAMED);
438     $params['userid'] = $userid;
440     $sql = "SELECT DISTINCT rc.capability, 1
442               FROM {role_assignments} ra
443               JOIN {context} actx ON actx.id = ra.contextid
444               JOIN {role_capabilities} rc ON rc.roleid = ra.roleid
445               JOIN {context} cctx ON cctx.id = rc.contextid
447              WHERE ra.userid = :userid
448                AND rc.capability $capcondition
449                AND rc.permission > 0
450                AND (".$DB->sql_concat('actx.path', "'/'")." LIKE ".$DB->sql_concat('cctx.path', "'/%'").
451                " OR ".$DB->sql_concat('cctx.path', "'/'")." LIKE ".$DB->sql_concat('actx.path', "'/%'").")";
453     if (!empty($CFG->defaultfrontpageroleid)) {
454         $frontpagecontext = context_course::instance(SITEID);
456         list($capcondition2, $params2) = $DB->get_in_or_equal(
457                 array_keys($unsurecapabilities), SQL_PARAMS_NAMED);
458         $params = array_merge($params, $params2);
459         $params['frontpageroleid'] = $CFG->defaultfrontpageroleid;
460         $params['frontpagepathpattern'] = $frontpagecontext->path . '/';
462         $sql .= "
463              UNION DISTINCT
465             SELECT DISTINCT rc.capability, 1
467               FROM {role_capabilities} rc
468               JOIN {context} cctx ON cctx.id = rc.contextid
470              WHERE rc.roleid = :frontpageroleid
471                AND rc.capability $capcondition2
472                AND rc.permission > 0
473                AND ".$DB->sql_concat('cctx.path', "'/'")." LIKE :frontpagepathpattern";
474     }
476     $relevantcapabilities = $DB->get_records_sql_menu($sql, $params);
478     // Add back any providers based on the detailed capability check.
479     foreach ($unsureproviders as $providerid => $provider) {
480         if (array_key_exists($provider->capability, $relevantcapabilities)) {
481             $providers[$providerid] = $provider;
482         }
483     }
485     return $providers;
488 /**
489  * Gets the message providers that are in the database for this component.
490  *
491  * This is an internal function used within messagelib.php
492  *
493  * @see message_update_providers()
494  * @param string $component A moodle component like 'moodle', 'mod_forum', 'block_quiz_results'
495  * @return array An array of message providers
496  */
497 function message_get_providers_from_db($component) {
498     global $DB;
500     return $DB->get_records('message_providers', array('component'=>$component), '', 'name, id, component, capability');  // Name is unique per component
503 /**
504  * Loads the messages definitions for a component from file
505  *
506  * If no messages are defined for the component, return an empty array.
507  * This is an internal function used within messagelib.php
508  *
509  * @see message_update_providers()
510  * @see message_update_processors()
511  * @param string $component A moodle component like 'moodle', 'mod_forum', 'block_quiz_results'
512  * @return array An array of message providers or empty array if not exists
513  */
514 function message_get_providers_from_file($component) {
515     $defpath = get_component_directory($component).'/db/messages.php';
517     $messageproviders = array();
519     if (file_exists($defpath)) {
520         require($defpath);
521     }
523     foreach ($messageproviders as $name => $messageprovider) {   // Fix up missing values if required
524         if (empty($messageprovider['capability'])) {
525             $messageproviders[$name]['capability'] = NULL;
526         }
527         if (empty($messageprovider['defaults'])) {
528             $messageproviders[$name]['defaults'] = array();
529         }
530     }
532     return $messageproviders;
535 /**
536  * Remove all message providers for particular component and corresponding settings
537  *
538  * @param string $component A moodle component like 'moodle', 'mod_forum', 'block_quiz_results'
539  * @return void
540  */
541 function message_provider_uninstall($component) {
542     global $DB;
544     $transaction = $DB->start_delegated_transaction();
545     $DB->delete_records('message_providers', array('component' => $component));
546     $DB->delete_records_select('config_plugins', "plugin = 'message' AND ".$DB->sql_like('name', '?', false), array("%_provider_{$component}_%"));
547     $DB->delete_records_select('user_preferences', $DB->sql_like('name', '?', false), array("message_provider_{$component}_%"));
548     $transaction->allow_commit();
551 /**
552  * Uninstall a message processor
553  *
554  * @param string $name A message processor name like 'email', 'jabber'
555  */
556 function message_processor_uninstall($name) {
557     global $DB;
559     $transaction = $DB->start_delegated_transaction();
560     $DB->delete_records('message_processors', array('name' => $name));
561     $DB->delete_records_select('config_plugins', "plugin = ?", array("message_{$name}"));
562     // delete permission preferences only, we do not care about loggedin/loggedoff
563     // defaults, they will be removed on the next attempt to update the preferences
564     $DB->delete_records_select('config_plugins', "plugin = 'message' AND ".$DB->sql_like('name', '?', false), array("{$name}_provider_%"));
565     $transaction->allow_commit();