MDL-29684 improve enrol_meta plugin

List of changes:
* configurable unenrol action
* new setting for synchronisation of all enrolled users or users with at least one role
* cron period increased to 1 hour in order to lower server load, courses should not get out of sync often
* CLI sync script for debugging or manual sync
* phpdocs fixes
* when plugin is disabled all roles are removed, enrollments are kept
* uninstall script
* other bugfixing

enrol/meta/addinstance_form.php

@@ -1,5 +1,4 @@
 <?php
-
 // This file is part of Moodle - http://moodle.org/
 //
 // Moodle is free software: you can redistribute it and/or modify
@@ -74,7 +73,7 @@ function definition() {
     function validation($data, $files) {
         global $DB, $CFG;
 
-        // TODO: this is duplicated here because it may be necessary one we implement ajax course selection element
+        // TODO: this is duplicated here because it may be necessary once we implement ajax course selection element
 
         $errors = parent::validation($data, $files);
         if (!$c = $DB->get_record('course', array('id'=>$data['link']))) {

enrol/meta/cli/sync.php

@@ -0,0 +1,66 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+/**
+ * CLI sync for meta course enrolments, use for debugging or immediate sync
+ * of all courses.
+ *
+ * Notes:
+ *   - it is required to use the web server account when executing PHP CLI scripts
+ *   - you need to change the "www-data" to match the apache user account
+ *   - use "su" if "sudo" not available
+ *
+ * @package    enrol
+ * @subpackage meta
+ * @copyright  2011 Petr Skoda {@link http://skodak.org}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+define('CLI_SCRIPT', true);
+
+require(dirname(dirname(dirname(dirname(__FILE__)))).'/config.php');
+require_once($CFG->libdir.'/clilib.php');
+require_once("$CFG->dirroot/enrol/meta/locallib.php");
+
+// now get cli options
+list($options, $unrecognized) = cli_get_params(array('verbose'=>false, 'help'=>false), array('v'=>'verbose', 'h'=>'help'));
+
+if ($unrecognized) {
+    $unrecognized = implode("\n  ", $unrecognized);
+    cli_error(get_string('cliunknowoption', 'admin', $unrecognized));
+}
+
+if ($options['help']) {
+    $help =
+        "Execute meta course enrol sync.
+
+Options:
+-v, --verbose         Print verbose progess information
+-h, --help            Print out this help
+
+Example:
+\$sudo -u www-data /usr/bin/php enrol/meta/cli/sync.php
+";
+
+    echo $help;
+    die;
+}
+
+$verbose = !empty($options['verbose']);
+
+$result = enrol_meta_sync(null, $verbose);
+
+exit($result);

enrol/meta/db/access.php

@@ -44,6 +44,16 @@
             'manager' => CAP_ALLOW,
         )
     ),
+
+    /* This is used only when sync suspends users instead of full unenrolment */
+    'enrol/meta:unenrol' => array(
+
+        'captype' => 'write',
+        'contextlevel' => CONTEXT_COURSE,
+        'archetypes' => array(
+            'manager' => CAP_ALLOW,
+        )
+    ),
 );
 
 

enrol/meta/db/uninstall.php

@@ -0,0 +1,41 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+/**
+ * Meta link enrolment plugin uninstallation.
+ *
+ * @package    enrol
+ * @subpackage meta
+ * @copyright  2011 Petr Skoda {@link http://skodak.org}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+defined('MOODLE_INTERNAL') || die();
+
+function xmldb_enrol_meta_uninstall() {
+    global $CFG, $DB;
+
+    $meta = enrol_get_plugin('meta');
+    $rs = $DB->get_recordset('enrol', array('enrol'=>'meta'));
+    foreach ($rs as $instance) {
+        $meta->delete_instance($instance);
+    }
+    $rs->close();
+
+    role_unassign_all(array('component'=>'enrol_meta'));
+
+    return true;
+}

enrol/meta/lang/en/enrol_meta.php

@@ -27,7 +27,10 @@
 $string['linkedcourse'] = 'Link course';
 $string['meta:config'] = 'Configure meta enrol instances';
 $string['meta:selectaslinked'] = 'Select course as meta linked';
+$string['meta:unenrol'] = 'Unenrol suspended users';
 $string['nosyncroleids'] = 'Roles that are not synchronised';
 $string['nosyncroleids_desc'] = 'By default all course level role assignments are synchronised from parent to child courses. Roles that are selected here will not be included in the synchronisation process. The roles available for synchronisation will be updated in the next cron execution.';
 $string['pluginname'] = 'Course meta link';
 $string['pluginname_desc'] = 'Course meta link enrolment plugin synchronises enrolments and roles in two different courses.';
+$string['syncall'] = 'Synchronise all enrolled users';
+$string['syncall_desc'] = 'If enabled all enrolled users are synchronised even if they have no role in parent course, if disabled only users that have at least one synchronised role are enrolled in child course.';

enrol/meta/lib.php

@@ -1,5 +1,4 @@
 <?php
-
 // This file is part of Moodle - http://moodle.org/
 //
 // Moodle is free software: you can redistribute it and/or modify
@@ -36,7 +35,7 @@ class enrol_meta_plugin extends enrol_plugin {
     /**
      * Returns localised name of enrol instance
      *
-     * @param object $instance (null is accepted too)
+     * @param stdClass $instance (null is accepted too)
      * @return string
      */
     public function get_instance_name($instance) {
@@ -67,13 +66,49 @@ public function get_newinstance_link($courseid) {
         return new moodle_url('/enrol/meta/addinstance.php', array('id'=>$courseid));
     }
 
+    /**
+     * Does this plugin allow manual unenrolment of a specific user?
+     * Yes, but only if user suspended...
+     *
+     * @param stdClass $instance course enrol instance
+     * @param stdClass $ue record from user_enrolments table
+     *
+     * @return bool - true means user with 'enrol/xxx:unenrol' may unenrol this user, false means nobody may touch this user enrolment
+     */
+    public function allow_unenrol_user(stdClass $instance, stdClass $ue) {
+        if ($ue->status == ENROL_USER_SUSPENDED) {
+            return true;
+        }
+
+        return false;
+    }
+
+    /**
+     * Gets an array of the user enrolment actions
+     *
+     * @param course_enrolment_manager $manager
+     * @param stdClass $ue A user enrolment object
+     * @return array An array of user_enrolment_actions
+     */
+    public function get_user_enrolment_actions(course_enrolment_manager $manager, $ue) {
+        $actions = array();
+        $context = $manager->get_context();
+        $instance = $ue->enrolmentinstance;
+        $params = $manager->get_moodlepage()->url->params();
+        $params['ue'] = $ue->id;
+        if ($this->allow_unenrol_user($instance, $ue) && has_capability('enrol/meta:unenrol', $context)) {
+            $url = new moodle_url('/enrol/unenroluser.php', $params);
+            $actions[] = new user_enrolment_action(new pix_icon('t/delete', ''), get_string('unenrol', 'enrol'), $url, array('class'=>'unenrollink', 'rel'=>$ue->id));
+        }
+        return $actions;
+    }
 
     /**
      * Called after updating/inserting course.
      *
      * @param bool $inserted true if course just inserted
-     * @param object $course
-     * @param object $data form data
+     * @param stdClass $course
+     * @param stdClass $data form data
      * @return void
      */
     public function course_updated($inserted, $course, $data) {
@@ -86,7 +121,22 @@ public function course_updated($inserted, $course, $data) {
         } else {
             // cohorts are never inserted automatically
         }
+    }
+
+    /**
+     * Update instance status
+     *
+     * @param stdClass $instance
+     * @param int $newstatus ENROL_INSTANCE_ENABLED, ENROL_INSTANCE_DISABLED
+     * @return void
+     */
+    public function update_status($instance, $newstatus) {
+        global $CFG;
+
+        parent::update_status($instance, $newstatus);
 
+        require_once("$CFG->dirroot/enrol/meta/locallib.php");
+        enrol_meta_sync($instance->courseid);
     }
 
     /**
@@ -96,12 +146,6 @@ public function course_updated($inserted, $course, $data) {
     public function cron() {
         global $CFG;
 
-        // purge all roles if meta sync disabled, those can be recreated later here in cron
-        if (!enrol_is_enabled('meta')) {
-            role_unassign_all(array('component'=>'meta_enrol'));
-            return;
-        }
-
         require_once("$CFG->dirroot/enrol/meta/locallib.php");
         enrol_meta_sync();
     }