MDL-46214 event: Support deprecation of events

This patch adds two new functions to the event base to allow deprecation of
the individual events, without entirely removing them from the UI.

This is different to our normal deprecation procedure because all events
must support display of historical data. It must also be possible to view
the event information in the event monitor.

admin/tool/monitor/classes/eventlist.php

@@ -67,7 +67,7 @@ protected static function get_core_eventlist() {
                 $ref = new \ReflectionClass($classname);
                 // Ignore abstracts.
                 if (!$ref->isAbstract() && $file != 'manager') {
-                    $eventinformation[$classname] = $classname::get_name();
+                    $eventinformation[$classname] = $classname::get_name_with_info();
                 }
             }
         }
@@ -109,9 +109,9 @@ protected static function get_non_core_eventlist($withoutcomponent = false) {
                         $ref = new \ReflectionClass($plugineventname);
                         if (!$ref->isAbstract() && $plugin != 'legacy') {
                             if ($withoutcomponent) {
-                                $noncorepluginlist[$plugineventname] = $plugineventname::get_name();
+                                $noncorepluginlist[$plugineventname] = $plugineventname::get_name_with_info();
                             } else {
-                                $noncorepluginlist[$plugintype . '_' . $plugin][$plugineventname] = $plugineventname::get_name();
+                                $noncorepluginlist[$plugintype . '_' . $plugin][$plugineventname] = $plugineventname::get_name_with_info();
                             }
                         }
                     }

admin/tool/monitor/classes/rule.php

@@ -202,7 +202,7 @@ public function get_mform_set_data() {
     public function get_event_name() {
         $eventclass = $this->eventname;
         if (class_exists($eventclass)) {
-            return $eventclass::get_name();
+            return $eventclass::get_name_with_info();
         }
         return get_string('eventnotfound', 'tool_monitor');
     }

admin/tool/monitor/classes/subscription.php

@@ -111,7 +111,7 @@ public function get_instance_name() {
     public function get_event_name() {
         $eventclass = $this->eventname;
         if (class_exists($eventclass)) {
-            return $eventclass::get_name();
+            return $eventclass::get_name_with_info();
         }
         return get_string('eventnotfound', 'tool_monitor');
     }

admin/tool/monitor/edit.php

@@ -54,12 +54,6 @@
 // Get data ready for mform.
 $eventlist = tool_monitor\eventlist::get_all_eventlist(true);
 $pluginlist = tool_monitor\eventlist::get_plugin_list();
-$eventlist = array_merge(array('' => get_string('choosedots')), $eventlist);
-$pluginlist = array_merge(array('' => get_string('choosedots')), $pluginlist);
-
-// Set up the yui module.
-$PAGE->requires->yui_module('moodle-tool_monitor-dropdown', 'Y.M.tool_monitor.DropDown.init',
-        array(array('eventlist' => $eventlist)));
 
 // Site level report.
 if (empty($courseid)) {
@@ -74,11 +68,25 @@
     $rule = \tool_monitor\rule_manager::get_rule($ruleid)->get_mform_set_data();
     $rule->minutes = $rule->timewindow / MINSECS;
     $subscriptioncount = \tool_monitor\subscription_manager::count_rule_subscriptions($ruleid);
+
+    // Filter out events which cannot be triggered for some reason.
+    $eventlist = array_filter($eventlist, function($classname) use ($rule) {
+        // Filter out all deprecated events, except for the current one.
+        return $classname === $rule->eventname || !$classname::is_deprecated();
+    }, ARRAY_FILTER_USE_KEY);
 } else {
     $rule = new stdClass();
     $subscriptioncount = 0;
+
+    // Filter out events which cannot be triggered for some reason.
+    $eventlist = array_filter($eventlist, function($classname) {
+        return !$classname::is_deprecated();
+    }, ARRAY_FILTER_USE_KEY);
 }
 
+// Modify the lists to add the choosers.
+$eventlist = array_merge(array('' => get_string('choosedots')), $eventlist);
+$pluginlist = array_merge(array('' => get_string('choosedots')), $pluginlist);
 $mform = new tool_monitor\rule_form(null, array('eventlist' => $eventlist, 'pluginlist' => $pluginlist, 'rule' => $rule,
         'courseid' => $courseid, 'subscriptioncount' => $subscriptioncount));
 
@@ -98,6 +106,10 @@
 
     redirect($manageurl);
 } else {
+    // Set up the yui module.
+    $PAGE->requires->yui_module('moodle-tool_monitor-dropdown', 'Y.M.tool_monitor.DropDown.init',
+            array(array('eventlist' => $eventlist)));
+
     echo $OUTPUT->header();
     $mform->set_data($rule);
     // If there's any subscription for this rule, display an information message.

lang/en/moodle.php

@@ -2027,6 +2027,7 @@
 $string['yourteacher'] = 'your {$a}';
 $string['yourwordforx'] = 'Your word for \'{$a}\'';
 $string['zippingbackup'] = 'Zipping backup';
+$string['deprecatedeventname'] = '{$a} (no longer in use)';
 
 // Deprecated since Moodle 3.1.
 $string['filetoolarge'] = 'is too large to upload';

lib/classes/event/base.php

@@ -305,6 +305,26 @@ public static function get_name() {
         return $parts[0].': '.str_replace('_', ' ', $parts[2]);
     }
 
+    /**
+     * Returns the event name complete with metadata information.
+     *
+     * This includes information about whether the event has been deprecated so should not be used in all situations -
+     * for example within reports themselves.
+     *
+     * If overriding this function, please ensure that you call the parent version too.
+     *
+     * @return string
+     */
+    public static function get_name_with_info() {
+        $return = static::get_name();
+
+        if (static::is_deprecated()) {
+            $return = get_string('deprecatedeventname', 'core', $return);
+        }
+
+        return $return;
+    }
+
     /**
      * Returns non-localised event description with id's for admin use only.
      *
@@ -961,4 +981,17 @@ public function __isset($name) {
     public function getIterator() {
         return new \ArrayIterator($this->data);
     }
+
+    /**
+     * Whether this event has been marked as deprecated.
+     *
+     * Events cannot be deprecated in the normal fashion as they must remain to support historical data.
+     * Once they are deprecated, there is no way to trigger the event, so it does not make sense to list it in some
+     * parts of the UI (e.g. Event Monitor).
+     *
+     * @return boolean
+     */
+    public static function is_deprecated() {
+        return false;
+    }
 }

lib/classes/event/mnet_access_control_updated.php

@@ -123,4 +123,8 @@ public static function get_other_mapping() {
         // Nothing to map.
         return false;
     }
+
+    public static function is_deprecated() {
+        return true;
+    }
 }

lib/upgrade.txt

@@ -52,6 +52,9 @@ information provided here is intended especially for developers.
 * All file_packer implementations now accept an additional parameter to allow a simple boolean return value instead of
   an array of individual file statuses.
 * "I set the field "field_string" to multiline:" now end with colon (:), as PyStrings is supposed to end with ":"
+* New functions to support deprecation of events have been added to the base event. See MDL-46214 for further details.
+* A new function `get_name_with_info` has been added to the base event. This function adds information about event
+  deprecations and should be used where this information is relevant.
 
 === 3.1 ===
 

report/eventlist/classes/list_generator.php

@@ -243,7 +243,7 @@ private static function format_data($eventdata, $eventfullpath) {
         $eventdata[$eventfullpath] = $eventfullpath::get_static_info();
         // Create a link for further event detail.
         $url = new \moodle_url('eventdetail.php', array('eventname' => $eventfullpath));
-        $link = \html_writer::link($url, $eventfullpath::get_name());
+        $link = \html_writer::link($url, $eventfullpath::get_name_with_info());
         $eventdata[$eventfullpath]['fulleventname'] = \html_writer::span($link);
         $eventdata[$eventfullpath]['fulleventname'] .= \html_writer::empty_tag('br');
         $eventdata[$eventfullpath]['fulleventname'] .= \html_writer::span($eventdata[$eventfullpath]['eventname'],
@@ -275,7 +275,7 @@ private static function format_data($eventdata, $eventfullpath) {
         }
 
         // Raw event data to be used to sort the "Event name" column.
-        $eventdata[$eventfullpath]['raweventname'] = $eventfullpath::get_name() . ' ' . $eventdata[$eventfullpath]['eventname'];
+        $eventdata[$eventfullpath]['raweventname'] = $eventfullpath::get_name_with_info() . ' ' . $eventdata[$eventfullpath]['eventname'];
 
         // Unset information that is not currently required.
         unset($eventdata[$eventfullpath]['action']);

report/eventlist/eventdetail.php

@@ -49,7 +49,7 @@
 }
 $filename = end($component);
 $eventfiles = $directory . '/' . $filename . '.php';
-$title = $eventname::get_name();
+$title = $eventname::get_name_with_info();
 
 // Define event information.
 $eventinformation = array('title' => $title);