MDL-40126 Enrolments: Implemented two webservices to get enrolment instance info
authorRajesh Taneja <rajesh@moodle.com>
Wed, 10 Jul 2013 01:42:56 +0000 (09:42 +0800)
committerRajesh Taneja <rajesh@moodle.com>
Mon, 29 Jul 2013 07:07:37 +0000 (15:07 +0800)
1. core_enrol_get_course_enrolment_methods() which returns all enrolment method instances
which implement get_enrol_info()
2. enrol_self_get_instance_info() will return information about self enrolment instance.

enrol/externallib.php
enrol/self/db/services.php [new file with mode: 0644]
enrol/self/externallib.php [new file with mode: 0644]
enrol/self/lib.php
enrol/self/tests/externallib_test.php [new file with mode: 0644]
enrol/self/version.php
enrol/tests/externallib_test.php
lib/db/services.php

index 582828e..ddfb976 100644 (file)
@@ -561,6 +561,64 @@ class core_enrol_external extends external_api {
         );
     }
 
+    /**
+     * Returns description of get_course_enrolment_methods() parameters
+     *
+     * @return external_function_parameters
+     */
+    public static function get_course_enrolment_methods_parameters() {
+        return new external_function_parameters(
+            array(
+                'courseid' => new external_value(PARAM_INT, 'Course id')
+            )
+        );
+    }
+
+    /**
+     * Get list of active course enrolment methods for current user.
+     *
+     * @param int $courseid
+     * @return array of course enrolment methods
+     */
+    public static function get_course_enrolment_methods($courseid) {
+
+        $params = self::validate_parameters(self::get_course_enrolment_methods_parameters(), array('courseid' => $courseid));
+
+        $coursecontext = context_course::instance($params['courseid']);
+        $categorycontext = $coursecontext->get_parent_context();
+        self::validate_context($categorycontext);
+
+        $result = array();
+        $enrolinstances = enrol_get_instances($params['courseid'], true);
+        foreach ($enrolinstances as $enrolinstance) {
+            if ($enrolplugin = enrol_get_plugin($enrolinstance->enrol)) {
+                if ($instanceinfo = $enrolplugin->get_enrol_info($enrolinstance)) {
+                    $result[] = (array) $instanceinfo;
+                }
+            }
+        }
+        return $result;
+    }
+
+    /**
+     * Returns description of get_course_enrolment_methods() result value
+     *
+     * @return external_description
+     */
+    public static function get_course_enrolment_methods_returns() {
+        return new external_multiple_structure(
+            new external_single_structure(
+                array(
+                    'id' => new external_value(PARAM_INT, 'id of course enrolment instance'),
+                    'courseid' => new external_value(PARAM_INT, 'id of course'),
+                    'type' => new external_value(PARAM_PLUGIN, 'type of enrolment plugin'),
+                    'name' => new external_value(PARAM_RAW, 'name of enrolment plugin'),
+                    'status' => new external_value(PARAM_RAW, 'status of enrolment plugin'),
+                    'wsfunction' => new external_value(PARAM_ALPHANUMEXT, 'webservice function to get more information', VALUE_OPTIONAL),
+                )
+            )
+        );
+    }
 }
 
 /**
diff --git a/enrol/self/db/services.php b/enrol/self/db/services.php
new file mode 100644 (file)
index 0000000..dd50355
--- /dev/null
@@ -0,0 +1,34 @@
+<?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/>.
+
+/**
+ * Self enrol plugin external functions and service definitions.
+ *
+ * @package   enrol_self
+ * @copyright 2013 Rajesh Taneja <rajesh@moodle.com>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since     Moodle 2.6
+ */
+
+$functions = array(
+    'enrol_self_get_instance_info' => array(
+        'classname'   => 'enrol_self_external',
+        'methodname'  => 'get_instance_info',
+        'classpath'   => 'enrol/self/externallib.php',
+        'description' => 'self enrolment instance information.',
+        'type'        => 'read'
+    )
+);
diff --git a/enrol/self/externallib.php b/enrol/self/externallib.php
new file mode 100644 (file)
index 0000000..4451087
--- /dev/null
@@ -0,0 +1,100 @@
+<?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/>.
+
+/**
+ * Self enrol plugin external functions
+ *
+ * @package    enrol_self
+ * @copyright  2013 Rajesh Taneja <rajesh@moodle.com>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+defined('MOODLE_INTERNAL') || die();
+
+require_once("$CFG->libdir/externallib.php");
+
+/**
+ * Self enrolment external functions.
+ *
+ * @package   enrol_self
+ * @copyright 2012 Rajesh Taneja <rajesh@moodle.com>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since     Moodle 2.6
+ */
+class enrol_self_external extends external_api {
+
+    /**
+     * Returns description of get_instance_info() parameters.
+     *
+     * @return external_function_parameters
+     */
+    public static function get_instance_info_parameters() {
+        return new external_function_parameters(
+                array('instanceid' => new external_value(PARAM_INT, 'instance id of self enrolment plugin.'))
+            );
+    }
+
+    /**
+     * Return self-enrolment instance information.
+     *
+     * @param int $instanceid instance id of self enrolment plugin.
+     * @return array instance information.
+     */
+    public static function get_instance_info($instanceid) {
+        global $DB, $CFG;
+
+        require_once($CFG->libdir . '/enrollib.php');
+
+        $params = self::validate_parameters(self::get_instance_info_parameters(), array('instanceid' => $instanceid));
+
+        // Retrieve self enrolment plugin.
+        $enrolplugin = enrol_get_plugin('self');
+        if (empty($enrolplugin)) {
+            throw new moodle_exception('invaliddata', 'error');
+        }
+
+        $enrolinstance = $DB->get_record('enrol', array('id' => $params['instanceid']), '*', MUST_EXIST);
+        $coursecontext = context_course::instance($enrolinstance->courseid);
+        $categorycontext = $coursecontext->get_parent_context();
+        self::validate_context($categorycontext);
+
+        $instanceinfo = (array) $enrolplugin->get_enrol_info($enrolinstance);
+        if (isset($instanceinfo['requiredparam']->enrolpassword)) {
+            $instanceinfo['enrolpassword'] = $instanceinfo['requiredparam']->enrolpassword;
+        }
+        unset($instanceinfo->requiredparam);
+
+        return $instanceinfo;
+    }
+
+    /**
+     * Returns description of get_instance_info() result value.
+     *
+     * @return external_description
+     */
+    public static function get_instance_info_returns() {
+        return new external_single_structure(
+            array(
+                'id' => new external_value(PARAM_INT, 'id of course enrolment instance'),
+                'courseid' => new external_value(PARAM_INT, 'id of course'),
+                'type' => new external_value(PARAM_PLUGIN, 'type of enrolment plugin'),
+                'name' => new external_value(PARAM_RAW, 'name of enrolment plugin'),
+                'status' => new external_value(PARAM_RAW, 'status of enrolment plugin'),
+                'enrolpassword' => new external_value(PARAM_RAW, 'password required for enrolment', VALUE_OPTIONAL),
+            )
+        );
+    }
+}
index 86a8899..9b0fa48 100644 (file)
@@ -335,6 +335,10 @@ class enrol_self_plugin extends enrol_plugin {
             $instanceinfo->requiredparam->enrolpassword = get_string('password', 'enrol_self');
         }
 
+        // If enrolment is possible and password is required then return ws function name to get more information.
+        if ((true === $instanceinfo->status) && $instance->password) {
+            $instanceinfo->wsfunction = 'enrol_self_get_instance_info';
+        }
         return $instanceinfo;
     }
 
diff --git a/enrol/self/tests/externallib_test.php b/enrol/self/tests/externallib_test.php
new file mode 100644 (file)
index 0000000..343af57
--- /dev/null
@@ -0,0 +1,96 @@
+<?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/>.
+
+/**
+ * Self enrol external PHPunit tests
+ *
+ * @package   enrol_self
+ * @copyright 2013 Rajesh Taneja <rajesh@moodle.com>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since     Moodle 2.6
+ */
+
+defined('MOODLE_INTERNAL') || die();
+
+global $CFG;
+
+require_once($CFG->dirroot . '/webservice/tests/helpers.php');
+require_once($CFG->dirroot . '/enrol/self/externallib.php');
+
+class enrol_self_external_testcase extends externallib_advanced_testcase {
+
+    /**
+     * Test get_instance_info
+     */
+    public function test_get_instance_info() {
+        global $DB;
+
+        $this->resetAfterTest(true);
+
+        // Check if self enrolment plugin is enabled.
+        $selfplugin = enrol_get_plugin('self');
+        $this->assertNotEmpty($selfplugin);
+
+        $studentrole = $DB->get_record('role', array('shortname'=>'student'));
+        $this->assertNotEmpty($studentrole);
+
+        $course = self::getDataGenerator()->create_course();
+
+        // Add enrolment methods for course.
+        $instanceid1 = $selfplugin->add_instance($course, array('status' => ENROL_INSTANCE_ENABLED,
+                                                                'name' => 'Test instance 1',
+                                                                'customint6' => 1,
+                                                                'roleid' => $studentrole->id));
+        $instanceid2 = $selfplugin->add_instance($course, array('status' => ENROL_INSTANCE_DISABLED,
+                                                                'customint6' => 1,
+                                                                'name' => 'Test instance 2',
+                                                                'roleid' => $studentrole->id));
+
+        $instanceid3 = $selfplugin->add_instance($course, array('status' => ENROL_INSTANCE_ENABLED,
+                                                                'roleid' => $studentrole->id,
+                                                                'customint6' => 1,
+                                                                'name' => 'Test instance 3',
+                                                                'password' => 'test'));
+
+        $enrolmentmethods = $DB->get_records('enrol', array('courseid' => $course->id, 'status' => ENROL_INSTANCE_ENABLED));
+        $this->assertCount(3, $enrolmentmethods);
+
+        $instanceinfo1 = enrol_self_external::get_instance_info($instanceid1);
+
+        $this->assertEquals($instanceid1, $instanceinfo1['id']);
+        $this->assertEquals($course->id, $instanceinfo1['courseid']);
+        $this->assertEquals('self', $instanceinfo1['type']);
+        $this->assertEquals('Test instance 1', $instanceinfo1['name']);
+        $this->assertTrue($instanceinfo1['status']);
+        $this->assertFalse(isset($instanceinfo1['enrolpassword']));
+
+        $instanceinfo2 = enrol_self_external::get_instance_info($instanceid2);
+        $this->assertEquals($instanceid2, $instanceinfo2['id']);
+        $this->assertEquals($course->id, $instanceinfo2['courseid']);
+        $this->assertEquals('self', $instanceinfo2['type']);
+        $this->assertEquals('Test instance 2', $instanceinfo2['name']);
+        $this->assertEquals(get_string('canntenrol', 'enrol_self'), $instanceinfo2['status']);
+        $this->assertFalse(isset($instanceinfo2['enrolpassword']));
+
+        $instanceinfo3 = enrol_self_external::get_instance_info($instanceid3);
+        $this->assertEquals($instanceid3, $instanceinfo3['id']);
+        $this->assertEquals($course->id, $instanceinfo3['courseid']);
+        $this->assertEquals('self', $instanceinfo3['type']);
+        $this->assertEquals('Test instance 3', $instanceinfo3['name']);
+        $this->assertTrue($instanceinfo3['status']);
+        $this->assertEquals(get_string('password', 'enrol_self'), $instanceinfo3['enrolpassword']);
+    }
+}
index c0d980e..b186821 100644 (file)
@@ -24,7 +24,7 @@
 
 defined('MOODLE_INTERNAL') || die();
 
-$plugin->version   = 2013062500;        // The current plugin version (Date: YYYYMMDDXX)
+$plugin->version   = 2013071100;        // The current plugin version (Date: YYYYMMDDXX)
 $plugin->requires  = 2013050100;        // Requires this Moodle version
 $plugin->component = 'enrol_self';      // Full name of the plugin (used for diagnostics)
 $plugin->cron      = 600;
index c93ebcb..b4e8c50 100644 (file)
@@ -155,4 +155,66 @@ class core_enrol_external_testcase extends externallib_advanced_testcase {
         $this->assertEquals(1, count($expecteduserlist['users']));
 
     }
+
+    /**
+     * Test get_course_enrolment_methods
+     */
+    public function test_get_course_enrolment_methods() {
+        global $DB;
+
+        $this->resetAfterTest(true);
+
+        // Get enrolment plugins.
+        $selfplugin = enrol_get_plugin('self');
+        $this->assertNotEmpty($selfplugin);
+        $manualplugin = enrol_get_plugin('manual');
+        $this->assertNotEmpty($manualplugin);
+
+        $studentrole = $DB->get_record('role', array('shortname'=>'student'));
+        $this->assertNotEmpty($studentrole);
+
+        $course1 = self::getDataGenerator()->create_course();
+        $course2 = self::getDataGenerator()->create_course();
+
+        // Add enrolment methods for course.
+        $instanceid1 = $selfplugin->add_instance($course1, array('status' => ENROL_INSTANCE_ENABLED,
+                                                                'name' => 'Test instance 1',
+                                                                'customint6' => 1,
+                                                                'roleid' => $studentrole->id));
+        $instanceid2 = $selfplugin->add_instance($course1, array('status' => ENROL_INSTANCE_DISABLED,
+                                                                'name' => 'Test instance 2',
+                                                                'roleid' => $studentrole->id));
+
+        $instanceid3 = $manualplugin->add_instance($course1, array('status' => ENROL_INSTANCE_ENABLED,
+                                                                'name' => 'Test instance 3'));
+
+        $enrolmentmethods = $DB->get_records('enrol', array('courseid' => $course1->id, 'status' => ENROL_INSTANCE_ENABLED));
+        $this->assertCount(2, $enrolmentmethods);
+
+        // Check if information is returned.
+        $enrolmentmethods = core_enrol_external::get_course_enrolment_methods($course1->id);
+        // Enrolment information is currently returned by self enrolment plugin, so count == 1.
+        // This should be changed as we implement get_enrol_info() for other enrolment plugins.
+        $this->assertCount(1, $enrolmentmethods);
+
+        $enrolmentmethod = $enrolmentmethods[0];
+        $this->assertEquals($course1->id, $enrolmentmethod['courseid']);
+        $this->assertEquals('self', $enrolmentmethod['type']);
+        $this->assertTrue($enrolmentmethod['status']);
+        $this->assertFalse(isset($enrolmentmethod['wsfunction']));
+
+        $instanceid4 = $selfplugin->add_instance($course2, array('status' => ENROL_INSTANCE_ENABLED,
+                                                                'name' => 'Test instance 4',
+                                                                'roleid' => $studentrole->id,
+                                                                'customint6' => 1,
+                                                                'password' => 'test'));
+        $enrolmentmethods = core_enrol_external::get_course_enrolment_methods($course2->id);
+        $this->assertCount(1, $enrolmentmethods);
+
+        $enrolmentmethod = $enrolmentmethods[0];
+        $this->assertEquals($course2->id, $enrolmentmethod['courseid']);
+        $this->assertEquals('self', $enrolmentmethod['type']);
+        $this->assertTrue($enrolmentmethod['status']);
+        $this->assertEquals('enrol_self_get_instance_info', $enrolmentmethod['wsfunction']);
+    }
 }
index ec515a8..6b377d7 100644 (file)
@@ -485,6 +485,14 @@ $functions = array(
         'capabilities'=> 'moodle/course:viewparticipants',
     ),
 
+    'core_enrol_get_course_enrolment_methods' => array(
+        'classname'   => 'core_enrol_external',
+        'methodname'  => 'get_course_enrolment_methods',
+        'classpath'   => 'enrol/externallib.php',
+        'description' => 'Get the list of course enrolment methods',
+        'type'        => 'read',
+    ),
+
     // === Role related functions ===
 
     'moodle_role_assign' => array(