Merge branch 'MDL-32027-master-1' of git://git.luns.net.uk/moodle
[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 parameter $eventdata structure:
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 - the full message in a given format
41  *  fullmessageformat  - the format if the full message (FORMAT_MOODLE, FORMAT_HTML, ..)
42  *  fullmessagehtml  - the full version (the message processor will choose with one to use)
43  *  smallmessage - the small version of the message
44  *  contexturl - 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.
45  *  contexturlname - the display text for contexturl
46  *
47  * @category message
48  * @param object $eventdata information about the message (component, userfrom, userto, ...)
49  * @return mixed the integer ID of the new message or false if there was a problem with a processor
50  */
51 function message_send($eventdata) {
52     global $CFG, $DB;
54     //new message ID to return
55     $messageid = false;
57     //TODO: we need to solve problems with database transactions here somehow, for now we just prevent transactions - sorry
58     $DB->transactions_forbidden();
60     if (is_int($eventdata->userto)) {
61         $eventdata->userto = $DB->get_record('user', array('id' => $eventdata->userto));
62     }
63     if (is_int($eventdata->userfrom)) {
64         $eventdata->userfrom = $DB->get_record('user', array('id' => $eventdata->userfrom));
65     }
66     if (!isset($eventdata->userto->auth) or !isset($eventdata->userto->suspended) or !isset($eventdata->userto->deleted)) {
67         $eventdata->userto = $DB->get_record('user', array('id' => $eventdata->userto->id));
68     }
70     //after how long inactive should the user be considered logged off?
71     if (isset($CFG->block_online_users_timetosee)) {
72         $timetoshowusers = $CFG->block_online_users_timetosee * 60;
73     } else {
74         $timetoshowusers = 300;//5 minutes
75     }
77     // Work out if the user is logged in or not
78     if (!empty($eventdata->userto->lastaccess) && (time()-$timetoshowusers) < $eventdata->userto->lastaccess) {
79         $userstate = 'loggedin';
80     } else {
81         $userstate = 'loggedoff';
82     }
84     // Create the message object
85     $savemessage = new stdClass();
86     $savemessage->useridfrom        = $eventdata->userfrom->id;
87     $savemessage->useridto          = $eventdata->userto->id;
88     $savemessage->subject           = $eventdata->subject;
89     $savemessage->fullmessage       = $eventdata->fullmessage;
90     $savemessage->fullmessageformat = $eventdata->fullmessageformat;
91     $savemessage->fullmessagehtml   = $eventdata->fullmessagehtml;
92     $savemessage->smallmessage      = $eventdata->smallmessage;
94     if (!empty($eventdata->notification)) {
95         $savemessage->notification = $eventdata->notification;
96     } else {
97         $savemessage->notification = 0;
98     }
100     if (!empty($eventdata->contexturl)) {
101         $savemessage->contexturl = $eventdata->contexturl;
102     } else {
103         $savemessage->contexturl = null;
104     }
106     if (!empty($eventdata->contexturlname)) {
107         $savemessage->contexturlname = $eventdata->contexturlname;
108     } else {
109         $savemessage->contexturlname = null;
110     }
112     $savemessage->timecreated = time();
114     // Fetch enabled processors
115     $processors = get_message_processors(true);
116     // Fetch default (site) preferences
117     $defaultpreferences = get_message_output_default_preferences();
119     // Preset variables
120     $processorlist = array();
121     $preferencebase = $eventdata->component.'_'.$eventdata->name;
122     // Fill in the array of processors to be used based on default and user preferences
123     foreach ($processors as $processor) {
124         // First find out permissions
125         $defaultpreference = $processor->name.'_provider_'.$preferencebase.'_permitted';
126         if (isset($defaultpreferences->{$defaultpreference})) {
127             $permitted = $defaultpreferences->{$defaultpreference};
128         } else {
129             //MDL-25114 They supplied an $eventdata->component $eventdata->name combination which doesn't
130             //exist in the message_provider table (thus there is no default settings for them)
131             $preferrormsg = get_string('couldnotfindpreference', 'message', $preferencename); //TODO: undefined $preferencename
132             throw new coding_exception($preferrormsg,'blah');
133         }
135         // Find out if user has configured this output
136         // Some processors cannot function without settings from the user
137         $userisconfigured = $processor->object->is_user_configured($eventdata->userto);
139         // DEBUG: notify if we are forcing unconfigured output
140         if ($permitted == 'forced' && !$userisconfigured) {
141             debugging('Attempt to force message delivery to user who has "'.$processor->name.'" output unconfigured', DEBUG_NORMAL);
142         }
144         // Warn developers that necessary data is missing regardless of how the processors are configured
145         if (!isset($eventdata->userto->emailstop)) {
146             debugging('userto->emailstop is not set. Retrieving it from the user table');
147             $eventdata->userto->emailstop = $DB->get_field('user', 'emailstop', array('id'=>$eventdata->userto->id));
148         }
150         // Populate the list of processors we will be using
151         if ($permitted == 'forced' && $userisconfigured) {
152             // An admin is forcing users to use this message processor. Use this processor unconditionally.
153             $processorlist[] = $processor->name;
154         } else if ($permitted == 'permitted' && $userisconfigured && !$eventdata->userto->emailstop) {
155             // User has not disabled notifications
156             // See if user set any notification preferences, otherwise use site default ones
157             $userpreferencename = 'message_provider_'.$preferencebase.'_'.$userstate;
158             if ($userpreference = get_user_preferences($userpreferencename, null, $eventdata->userto->id)) {
159                 if (in_array($processor->name, explode(',', $userpreference))) {
160                     $processorlist[] = $processor->name;
161                 }
162             } else if (isset($defaultpreferences->{$userpreferencename})) {
163                 if (in_array($processor->name, explode(',', $defaultpreferences->{$userpreferencename}))) {
164                     $processorlist[] = $processor->name;
165                 }
166             }
167         }
168     }
170     if (empty($processorlist) && $savemessage->notification) {
171         //if they have deselected all processors and its a notification mark it read. The user doesnt want to be bothered
172         $savemessage->timeread = time();
173         $messageid = $DB->insert_record('message_read', $savemessage);
174     } else {                        // Process the message
175         // Store unread message just in case we can not send it
176         $messageid = $savemessage->id = $DB->insert_record('message', $savemessage);
177         $eventdata->savedmessageid = $savemessage->id;
179         // Try to deliver the message to each processor
180         if (!empty($processorlist)) {
181             foreach ($processorlist as $procname) {
182                 if (!$processors[$procname]->object->send_message($eventdata)) {
183                     debugging('Error calling message processor '.$procname);
184                     $messageid = false;
185                 }
186             }
188             //if messaging is disabled and they previously had forum notifications handled by the popup processor
189             //or any processor that puts a row in message_working then the notification will remain forever
190             //unread. To prevent this mark the message read if messaging is disabled
191             if (empty($CFG->messaging)) {
192                 require_once($CFG->dirroot.'/message/lib.php');
193                 $messageid = message_mark_message_read($savemessage, time());
194             } else if ( $DB->count_records('message_working', array('unreadmessageid' => $savemessage->id)) == 0){
195                 //if there is no more processors that want to process this we can move message to message_read
196                 require_once($CFG->dirroot.'/message/lib.php');
197                 $messageid = message_mark_message_read($savemessage, time(), true);
198             }
199         }
200     }
202     return $messageid;
206 /**
207  * Updates the message_providers table with the current set of message providers
208  *
209  * @param string $component For example 'moodle', 'mod_forum' or 'block_quiz_results'
210  * @return boolean True on success
211  */
212 function message_update_providers($component='moodle') {
213     global $DB;
215     // load message providers from files
216     $fileproviders = message_get_providers_from_file($component);
218     // load message providers from the database
219     $dbproviders = message_get_providers_from_db($component);
221     foreach ($fileproviders as $messagename => $fileprovider) {
223         if (!empty($dbproviders[$messagename])) {   // Already exists in the database
224             // check if capability has changed
225             if ($dbproviders[$messagename]->capability == $fileprovider['capability']) {  // Same, so ignore
226                 // exact same message provider already present in db, ignore this entry
227                 unset($dbproviders[$messagename]);
228                 continue;
230             } else {                                // Update existing one
231                 $provider = new stdClass();
232                 $provider->id         = $dbproviders[$messagename]->id;
233                 $provider->capability = $fileprovider['capability'];
234                 $DB->update_record('message_providers', $provider);
235                 unset($dbproviders[$messagename]);
236                 continue;
237             }
239         } else {             // New message provider, add it
241             $provider = new stdClass();
242             $provider->name       = $messagename;
243             $provider->component  = $component;
244             $provider->capability = $fileprovider['capability'];
246             $transaction = $DB->start_delegated_transaction();
247             $DB->insert_record('message_providers', $provider);
248             message_set_default_message_preference($component, $messagename, $fileprovider);
249             $transaction->allow_commit();
250         }
251     }
253     foreach ($dbproviders as $dbprovider) {  // Delete old ones
254         $DB->delete_records('message_providers', array('id' => $dbprovider->id));
255         $DB->delete_records_select('config_plugins', "plugin = 'message' AND ".$DB->sql_like('name', '?', false), array("%_provider_{$component}_{$dbprovider->name}_%"));
256         $DB->delete_records_select('user_preferences', $DB->sql_like('name', '?', false), array("message_provider_{$component}_{$dbprovider->name}_%"));
257     }
259     return true;
262 /**
263  * This function populates default message preferences for all existing providers
264  * when the new message processor is added.
265  *
266  * @param string $processorname The name of message processor plugin (e.g. 'email', 'jabber')
267  * @throws invalid_parameter_exception if $processorname does not exist in the database
268  */
269 function message_update_processors($processorname) {
270     global $DB;
272     // validate if our processor exists
273     $processor = $DB->get_records('message_processors', array('name' => $processorname));
274     if (empty($processor)) {
275         throw new invalid_parameter_exception();
276     }
278     $providers = $DB->get_records_sql('SELECT DISTINCT component FROM {message_providers}');
280     $transaction = $DB->start_delegated_transaction();
281     foreach ($providers as $provider) {
282         // load message providers from files
283         $fileproviders = message_get_providers_from_file($provider->component);
284         foreach ($fileproviders as $messagename => $fileprovider) {
285             message_set_default_message_preference($provider->component, $messagename, $fileprovider, $processorname);
286         }
287     }
288     $transaction->allow_commit();
291 /**
292  * Setting default messaging preferences for particular message provider
293  *
294  * @param  string $component   The name of component (e.g. moodle, mod_forum, etc.)
295  * @param  string $messagename The name of message provider
296  * @param  array  $fileprovider The value of $messagename key in the array defined in plugin messages.php
297  * @param  string $processorname The optional name of message processor
298  */
299 function message_set_default_message_preference($component, $messagename, $fileprovider, $processorname='') {
300     global $DB;
302     // Fetch message processors
303     $condition = null;
304     // If we need to process a particular processor, set the select condition
305     if (!empty($processorname)) {
306        $condition = array('name' => $processorname);
307     }
308     $processors = $DB->get_records('message_processors', $condition);
310     // load default messaging preferences
311     $defaultpreferences = get_message_output_default_preferences();
313     // Setting default preference
314     $componentproviderbase = $component.'_'.$messagename;
315     $loggedinpref = array();
316     $loggedoffpref = array();
317     // set 'permitted' preference first for each messaging processor
318     foreach ($processors as $processor) {
319         $preferencename = $processor->name.'_provider_'.$componentproviderbase.'_permitted';
320         // if we do not have this setting yet, set it
321         if (!isset($defaultpreferences->{$preferencename})) {
322             // determine plugin default settings
323             $plugindefault = 0;
324             if (isset($fileprovider['defaults'][$processor->name])) {
325                 $plugindefault = $fileprovider['defaults'][$processor->name];
326             }
327             // get string values of the settings
328             list($permitted, $loggedin, $loggedoff) = translate_message_default_setting($plugindefault, $processor->name);
329             // store default preferences for current processor
330             set_config($preferencename, $permitted, 'message');
331             // save loggedin/loggedoff settings
332             if ($loggedin) {
333                 $loggedinpref[] = $processor->name;
334             }
335             if ($loggedoff) {
336                 $loggedoffpref[] = $processor->name;
337             }
338         }
339     }
340     // now set loggedin/loggedoff preferences
341     if (!empty($loggedinpref)) {
342         $preferencename = 'message_provider_'.$componentproviderbase.'_loggedin';
343         if (isset($defaultpreferences->{$preferencename})) {
344             // We have the default preferences for this message provider, which
345             // likely means that we have been adding a new processor. Add defaults
346             // to exisitng preferences.
347             $loggedinpref = array_merge($loggedinpref, explode(',', $defaultpreferences->{$preferencename}));
348         }
349         set_config($preferencename, join(',', $loggedinpref), 'message');
350     }
351     if (!empty($loggedoffpref)) {
352         $preferencename = 'message_provider_'.$componentproviderbase.'_loggedoff';
353         if (isset($defaultpreferences->{$preferencename})) {
354             // We have the default preferences for this message provider, which
355             // likely means that we have been adding a new processor. Add defaults
356             // to exisitng preferences.
357             $loggedoffpref = array_merge($loggedoffpref, explode(',', $defaultpreferences->{$preferencename}));
358         }
359         set_config($preferencename, join(',', $loggedoffpref), 'message');
360     }
363 /**
364  * This function has been deprecated please use {@link message_get_providers_for_user()} instead.
365  *
366  * Returns the active providers for the current user, based on capability
367  *
368  * @see message_get_providers_for_user()
369  * @deprecated since 2.1
370  * @todo Remove in 2.2 (MDL-31031)
371  * @return array An array of message providers
372  */
373 function message_get_my_providers() {
374     global $USER;
375     return message_get_providers_for_user($USER->id);
378 /**
379  * Returns the active providers for the user specified, based on capability
380  *
381  * @param int $userid id of user
382  * @return array An array of message providers
383  */
384 function message_get_providers_for_user($userid) {
385     global $DB, $CFG;
387     $systemcontext = get_context_instance(CONTEXT_SYSTEM);
389     $providers = $DB->get_records('message_providers', null, 'name');
391     // Remove all the providers we aren't allowed to see now
392     foreach ($providers as $providerid => $provider) {
393         if (!empty($provider->capability)) {
394             if (!has_capability($provider->capability, $systemcontext, $userid)) {
395                 unset($providers[$providerid]);   // Not allowed to see this
396             }
397         }
398         // Ensure user is not allowed to configure instantmessage if it is globally disabled.
399         if (!$CFG->messaging && $provider->name == 'instantmessage') {
400             unset($providers[$providerid]);
401         }
402     }
404     return $providers;
407 /**
408  * Gets the message providers that are in the database for this component.
409  *
410  * This is an internal function used within messagelib.php
411  *
412  * @see message_update_providers()
413  * @param string $component A moodle component like 'moodle', 'mod_forum', 'block_quiz_results'
414  * @return array An array of message providers
415  */
416 function message_get_providers_from_db($component) {
417     global $DB;
419     return $DB->get_records('message_providers', array('component'=>$component), '', 'name, id, component, capability');  // Name is unique per component
422 /**
423  * Loads the messages definitions for a component from file
424  *
425  * If no messages are defined for the component, return an empty array.
426  * This is an internal function used within messagelib.php
427  *
428  * @see message_update_providers()
429  * @see message_update_processors()
430  * @param string $component A moodle component like 'moodle', 'mod_forum', 'block_quiz_results'
431  * @return array An array of message providers or empty array if not exists
432  */
433 function message_get_providers_from_file($component) {
434     $defpath = get_component_directory($component).'/db/messages.php';
436     $messageproviders = array();
438     if (file_exists($defpath)) {
439         require($defpath);
440     }
442     foreach ($messageproviders as $name => $messageprovider) {   // Fix up missing values if required
443         if (empty($messageprovider['capability'])) {
444             $messageproviders[$name]['capability'] = NULL;
445         }
446         if (empty($messageprovider['defaults'])) {
447             $messageproviders[$name]['defaults'] = array();
448         }
449     }
451     return $messageproviders;
454 /**
455  * Remove all message providers for particular component and corresponding settings
456  *
457  * @param string $component A moodle component like 'moodle', 'mod_forum', 'block_quiz_results'
458  * @return void
459  */
460 function message_provider_uninstall($component) {
461     global $DB;
463     $transaction = $DB->start_delegated_transaction();
464     $DB->delete_records('message_providers', array('component' => $component));
465     $DB->delete_records_select('config_plugins', "plugin = 'message' AND ".$DB->sql_like('name', '?', false), array("%_provider_{$component}_%"));
466     $DB->delete_records_select('user_preferences', $DB->sql_like('name', '?', false), array("message_provider_{$component}_%"));
467     $transaction->allow_commit();
470 /**
471  * Uninstall a message processor
472  *
473  * @param string $name A message processor name like 'email', 'jabber'
474  */
475 function message_processor_uninstall($name) {
476     global $DB;
478     $transaction = $DB->start_delegated_transaction();
479     $DB->delete_records('message_processors', array('name' => $name));
480     // delete permission preferences only, we do not care about loggedin/loggedoff
481     // defaults, they will be removed on the next attempt to update the preferences
482     $DB->delete_records_select('config_plugins', "plugin = 'message' AND ".$DB->sql_like('name', '?', false), array("{$name}_provider_%"));
483     $transaction->allow_commit();