MDL-27171 messages: implement new syntax in messages.php and update processing

The new messaging default settings can be set in messages.php and deployed
during installation. This also ensures the removing of settings on plugin
uninstallation and contains the update script to populate current default
settings on the existing system when the new feature is introduced.

For security reason we have to avoid using library functions in upgrade
function, so we set defaults the blind way. At this point we do not expect
plugins to have individual messaging defaults presets anyway. The site
defaults are the same as were set for each user using
message_set_default_message_preferences function.

Signed-off-by: Ruslan Kabalin <ruslan.kabalin@luns.net.uk>

admin/index.php

@@ -355,7 +355,6 @@ if (during_initial_install()) {
         }
         // login user and let him set password and admin details
         $adminuser->newadminuser = 1;
-        message_set_default_message_preferences($adminuser);
         complete_user_login($adminuser, false);
         redirect("$CFG->wwwroot/user/editadvanced.php?id=$adminuser->id"); // Edit thyself
 

lang/en/message.php

@@ -37,7 +37,6 @@ $string['blockcontact'] = 'Block contact';
 $string['blockedmessages'] = '{$a} message(s) to/from blocked users';
 $string['blockedusers'] = 'Blocked users ({$a})';
 $string['blocknoncontacts'] = 'Prevent non-contacts from messaging me';
-$string['cannotsavemessageprefs'] = 'Could not save user messaging preferences';
 $string['contactlistempty'] = 'Your contact list is empty';
 $string['contacts'] = 'Contacts';
 $string['context'] = 'context';
@@ -53,6 +52,7 @@ $string['emailmessages'] = 'Email messages when I am offline';
 $string['emailtagline'] = 'This is a copy of a message sent to you at "{$a->sitename}". Go to {$a->url} to reply.';
 $string['emptysearchstring'] = 'You must search for something';
 $string['errorcallingprocessor'] = 'Error calling defined processor';
+$string['errortranslatingdefault'] = 'Error translating default setting provided by plugin, using system defaults instead.';
 $string['forced'] = 'Forced';
 $string['formorethan'] = 'For more than';
 $string['guestnoeditmessage'] = 'Guest user can not edit messaging options';

lib/db/install.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8" ?>
-<XMLDB PATH="lib/db" VERSION="20110523" COMMENT="XMLDB file for core Moodle tables"
+<XMLDB PATH="lib/db" VERSION="20110525" COMMENT="XMLDB file for core Moodle tables"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:noNamespaceSchemaLocation="../../lib/xmldb/xmldb.xsd"
 >
@@ -2220,8 +2220,9 @@
     </TABLE>
     <TABLE NAME="message_processors" COMMENT="List of message output plugins" PREVIOUS="message_providers" NEXT="message_working">
       <FIELDS>
-        <FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="false" SEQUENCE="true" COMMENT="id of the table, please edit me" NEXT="name"/>
+        <FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="false" SEQUENCE="true" NEXT="name"/>
-        <FIELD NAME="name" TYPE="char" LENGTH="166" NOTNULL="true" SEQUENCE="false" COMMENT="Default comment for the field, please edit me" PREVIOUS="id"/>
+        <FIELD NAME="name" TYPE="char" LENGTH="166" NOTNULL="true" SEQUENCE="false" COMMENT="Name of the message processor" PREVIOUS="id" NEXT="enabled"/>
+        <FIELD NAME="enabled" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="1" SEQUENCE="false" COMMENT="Defines if processor is enabled" PREVIOUS="name"/>
       </FIELDS>
       <KEYS>
         <KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="primary key of the table, please edit me"/>

lib/db/messages.php

@@ -39,6 +39,10 @@ $messageproviders = array (
     ),
 
     'instantmessage' => array (
+        'defaults' => array(
+            'popup' => MESSAGE_PERMITTED + MESSAGE_DEFAULT_LOGGEDIN + MESSAGE_DEFAULT_LOGGEDOFF,
+            'email' => MESSAGE_PERMITTED + MESSAGE_DEFAULT_LOGGEDOFF,
+        ),
     ),
 
     'backup' => array (

lib/db/upgrade.php

@@ -6122,6 +6122,11 @@ WHERE gradeitemid IS NOT NULL AND grademax IS NOT NULL");
         if (!$dbman->field_exists($table,$field)) {
             $dbman->add_field($table, $field);
         }
+
+        // Populate default messaging settings
+        upgrade_populate_default_messaging_prefs();
+
+        upgrade_main_savepoint(true, 2011052500.01);
     }
 
     return true;

lib/db/upgradelib.php

@@ -645,3 +645,54 @@ function update_fix_automated_backup_config() {
     unset_config('backup_sche_gradebook_history');
     unset_config('disablescheduleddbackups');
 }
+
+/**
+ * This function is used to set default messaging preferences when the new
+ * admin-level messaging defaults settings have been introduced.
+ */
+function upgrade_populate_default_messaging_prefs() {
+    global $DB;
+
+    $providers = $DB->get_records('message_providers');
+    $processors = $DB->get_records('message_processors');
+    $defaultpreferences = $DB->get_records_menu('config_plugins', array('plugin'=>'message'), '', 'name,value');
+
+    $transaction = $DB->start_delegated_transaction();
+
+    $setting = new stdClass();
+    $setting->plugin = 'message';
+
+    foreach ($providers as $provider) {
+        $componentproviderbase = $provider->component.'_'.$provider->name;
+        // set MESSAGE_PERMITTED to all combinations of message types
+        // (providers) and outputs (processors)
+        foreach ($processors as $processor) {
+            $preferencename = $processor->name.'_provider_'.$componentproviderbase.'_permitted';
+            if (!array_key_exists($preferencename, $defaultpreferences)) {
+                $setting->name = $preferencename;
+                $setting->value = 'permitted';
+                $DB->insert_record('config_plugins', $setting);
+            }
+        }
+        // for email output we also have to set MESSAGE_DEFAULT_OFFLINE + MESSAGE_DEFAULT_ONLINE
+        foreach(array('loggedin', 'loggedoff') as $state) {
+            $preferencename = 'message_provider_'.$componentproviderbase.'_'.$state;
+            if (!array_key_exists($preferencename, $defaultpreferences)) {
+                $setting->name = $preferencename;
+                $setting->value = 'email';
+                // except instant message where default for popup should be
+                // MESSAGE_DEFAULT_LOGGEDIN + MESSAGE_DEFAULT_LOGGEDOFF and for email
+                // MESSAGE_DEFAULT_LOGGEDOFF.
+                if ($componentproviderbase == 'moodle_instantmessage') {
+                    if  ($state == 'loggedoff') {
+                        $setting->value = 'email,popup';
+                    } else {
+                        $setting->value = 'popup';
+                    }
+                }
+                $DB->insert_record('config_plugins', $setting);
+            }
+        }
+    }
+    $transaction->allow_commit();
+}

lib/installlib.php

@@ -574,7 +574,6 @@ function install_cli_database(array $options, $interactive) {
     $admins = get_admins();
     $admin = reset($admins);
     session_set_user($admin);
-    message_set_default_message_preferences($admin);
 
     // apply all default settings, do it twice to fill all defaults - some settings depend on other setting
     admin_apply_default_settings(NULL, true);

lib/messagelib.php

@@ -232,7 +232,10 @@ function message_update_providers($component='moodle') {
             $provider->component  = $component;
             $provider->capability = $fileprovider['capability'];
 
+            $transaction = $DB->start_delegated_transaction();
             $DB->insert_record('message_providers', $provider);
+            message_set_default_message_preference($component, $messagename, $fileprovider);
+            $transaction->allow_commit();
         }
     }
 
@@ -243,6 +246,58 @@ function message_update_providers($component='moodle') {
     return true;
 }
 
+/**
+ * Setting default messaging preference for particular message provider
+ * @param  string $component   The name of component (e.g. moodle, mod_forum, etc.)
+ * @param  string $messagename The name of message provider
+ * @param  array  $fileprovider The value of $messagename key in the array defined in plugin messages.php
+ * @return bool
+ */
+function message_set_default_message_preference($component, $messagename, $fileprovider) {
+    global $DB;
+
+    // Fetch message processors
+    $processors = get_message_processors();
+
+    // load default messaging preferences
+    $defaultpreferences = get_message_output_default_preferences();
+
+    // Setting site default preferences
+    $componentproviderbase = $component.'_'.$messagename;
+    $loggedinpref = array();
+    $loggedoffpref = array();
+    foreach ($processors as $processor) {
+        $preferencename = $processor->name.'_provider_'.$componentproviderbase.'_permitted';
+        if (!array_key_exists($preferencename, $defaultpreferences)) {
+            // determine plugin default settings
+            $plugindefault = 0;
+            if (isset($fileprovider['defaults'][$processor->name])) {
+                $plugindefault = $fileprovider['defaults'][$processor->name];
+            }
+            // get string values of the settings
+            list($permitted, $loggedin, $loggedoff) = translate_message_default_setting($plugindefault, $processor->name);
+            // store default preferences for current processor
+            set_config($preferencename, $permitted, 'message');
+            // save loggedin/loggedoff settings
+            if ($loggedin) {
+                $loggedinpref[] = $processor->name;
+            }
+            if ($loggedoff) {
+                $loggedoffpref[] = $processor->name;
+            }
+        }
+    }
+    // store loggedin/loggedoff preferences
+    if (!empty($loggedinpref)) {
+        $preferencename = 'message_provider_'.$componentproviderbase.'_loggedin';
+        set_config($preferencename, join(',', $loggedinpref), 'message');
+    }
+    if (!empty($loggedoffpref)) {
+        $preferencename = 'message_provider_'.$componentproviderbase.'_loggedoff';
+        set_config($preferencename, join(',', $loggedoffpref), 'message');
+    }
+}
+
 /**
  * Returns the active providers for the current user, based on capability
  * @return array of message providers
@@ -300,6 +355,9 @@ function message_get_providers_from_file($component) {
         if (empty($messageprovider['capability'])) {
             $messageproviders[$name]['capability'] = NULL;
         }
+        if (empty($messageprovider['defaults'])) {
+            $messageproviders[$name]['defaults'] = array();
+        }
     }
 
     return $messageproviders;
@@ -311,53 +369,12 @@ function message_get_providers_from_file($component) {
  */
 function message_uninstall($component) {
     global $DB;
-    return $DB->delete_records('message_providers', array('component' => $component));
+
-}
+    $transaction = $DB->start_delegated_transaction();
-
+    $DB->delete_records('message_providers', array('component' => $component));
-/**
+    $DB->delete_records_select('config_plugins', "plugin = 'message' AND ".$DB->sql_like('name', '?', false), array("%_provider_{$component}_%"));
- * Set default message preferences.
+    $DB->delete_records_select('user_preferences', $DB->sql_like('name', '?', false), array("message_provider_{$component}_%"));
- * @param $user - User to set message preferences
+    $transaction->allow_commit();
- */
+
-function message_set_default_message_preferences($user) {
+    return true;
-    global $DB;
-
-    //check for the pre 2.0 disable email setting
-    $useemail = empty($user->emailstop);
-
-    //look for the pre-2.0 preference if it exists
-    $oldpreference = get_user_preferences('message_showmessagewindow', -1, $user->id);
-    //if they elected to see popups or the preference didnt exist
-    $usepopups = (intval($oldpreference)==1 || intval($oldpreference)==-1);
-
-    $defaultonlineprocessor = 'none';
-    $defaultofflineprocessor = 'none';
-    
-    if ($useemail) {
-        $defaultonlineprocessor = 'email';
-        $defaultofflineprocessor = 'email';
-    } else if ($usepopups) {
-        $defaultonlineprocessor = 'popup';
-        $defaultofflineprocessor = 'popup';
-    }
-
-    $offlineprocessortouse = $onlineprocessortouse = null;
-
-    $providers = $DB->get_records('message_providers');
-    $preferences = array();
-
-    foreach ($providers as $providerid => $provider) {
-
-        //force some specific defaults for IMs
-        if ($provider->name=='instantmessage' && $usepopups && $useemail) {
-            $onlineprocessortouse = 'popup';
-            $offlineprocessortouse = 'email,popup';
-        } else {
-            $onlineprocessortouse = $defaultonlineprocessor;
-            $offlineprocessortouse = $defaultofflineprocessor;
-        }
-        
-        $preferences['message_provider_'.$provider->component.'_'.$provider->name.'_loggedin'] = $onlineprocessortouse;
-        $preferences['message_provider_'.$provider->component.'_'.$provider->name.'_loggedoff'] = $offlineprocessortouse;
-    }
-    return set_user_preferences($preferences, $user->id);
 }

message/edit.php

@@ -98,7 +98,7 @@ if (($form = data_submitted()) && confirm_sesskey()) {
 
 /// Set all the preferences for all the message providers
     $providers = message_get_my_providers();
-    foreach ( $providers as $provider) {
+    foreach ($providers as $provider) {
         $componentproviderbase = $provider->component.'_'.$provider->name;
         foreach (array('loggedin', 'loggedoff') as $state) {
             $linepref = '';

message/lib.php

@@ -53,6 +53,25 @@ define('MESSAGE_SEARCH_MAX_RESULTS', 200);
 define('MESSAGE_CONTACTS_PER_PAGE',10);
 define('MESSAGE_MAX_COURSE_NAME_LENGTH', 30);
 
+/**
+ * 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 when user is loggedin (MESSAGE_DEFAULT_LOGGEDIN)
+ * bit 1 - whether to send message when user is loggedoff (MESSAGE_DEFAULT_LOGGEDOFF)
+ * bit 2..3 - messaging permission (MESSAGE_DISALLOWED|MESSAGE_PERMITTED|MESSAGE_FORCED)
+ *
+ * MESSAGE_PERMITTED_MASK contains the mask we use to distinguish permission setting
+ */
+
+define('MESSAGE_DEFAULT_LOGGEDIN', 0x01); // 0001
+define('MESSAGE_DEFAULT_LOGGEDOFF', 0x02); // 0010
+
+define('MESSAGE_DISALLOWED', 0x04); // 0100
+define('MESSAGE_PERMITTED', 0x08); // 1000
+define('MESSAGE_FORCED', 0x0c); // 1100
+
+define('MESSAGE_PERMITTED_MASK', 0x0c); // 1100
+
 /**
  * Set default value for default outputs permitted setting
  */
@@ -2231,3 +2250,53 @@ function get_message_output_default_preferences() {
     }
     return $preferences;
 }
+
+/**
+ * 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.
+ * @param  int    $plugindefault Default setting suggested by plugin
+ * @param  string $processorname The name of processor
+ * @return array  $settings array of strings in the order: $permitted, $loggedin, $loggedoff.
+ */
+function translate_message_default_setting($plugindefault, $processorname) {
+    // Preset translation arrays
+    $permittedvalues = array(
+        0x04 => 'disallowed',
+        0x08 => 'permitted',
+        0x0c => 'forced',
+    );
+
+    $loggedinstatusvalues = array(
+        0x00 => null, // use null if loggedin/loggedoff is not defined
+        0x01 => 'loggedin',
+        0x02 => 'loggedoff',
+    );
+
+    // define the default setting
+    if ($processorname == 'email') {
+        $default = MESSAGE_PERMITTED + MESSAGE_DEFAULT_LOGGEDIN + MESSAGE_DEFAULT_LOGGEDOFF;
+    } else {
+        $default = MESSAGE_PERMITTED;
+    }
+
+    // Validate the value. It should not exceed the maximum size
+    if (!is_int($plugindefault) || ($plugindefault > 0x0f)) {
+        notify(get_string('errortranslatingdefault', 'message'));
+        $plugindefault = $default;
+    }
+    // Use plugin default setting of 'permitted' is 0
+    if (!($plugindefault & MESSAGE_PERMITTED_MASK)) {
+        $plugindefault = $default;
+    }
+
+    $permitted = $permittedvalues[$plugindefault & MESSAGE_PERMITTED_MASK];
+    $loggedin = $loggedoff = 0x00;
+
+    if (($plugindefault & MESSAGE_PERMITTED_MASK) == MESSAGE_PERMITTED) {
+        $loggedin = $loggedinstatusvalues[$plugindefault & ~MESSAGE_PERMITTED_MASK & MESSAGE_DEFAULT_LOGGEDIN];
+        $loggedoff = $loggedinstatusvalues[$plugindefault & ~MESSAGE_PERMITTED_MASK & MESSAGE_DEFAULT_LOGGEDOFF];
+    }
+
+    return array($permitted, $loggedin, $loggedoff);
+}

user/editadvanced.php

@@ -200,10 +200,6 @@ if ($usernew = $userform->get_data()) {
 
     // trigger events
     if ($usercreated) {
-        //set default message preferences
-        if (!message_set_default_message_preferences( $usernew )){
-            print_error('cannotsavemessageprefs', 'message');
-        }
         events_trigger('user_created', $usernew);
     } else {
         events_trigger('user_updated', $usernew);