From be9bf94e4ae76e0b4fdfeb259e3f7a5c56c56055 Mon Sep 17 00:00:00 2001 From: Rajesh Taneja Date: Wed, 10 Jul 2013 09:42:56 +0800 Subject: [PATCH] MDL-40126 Enrolments: Implemented two webservices to get enrolment instance info 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 | 58 +++++++++++++++ enrol/self/db/services.php | 34 +++++++++ enrol/self/externallib.php | 100 ++++++++++++++++++++++++++ enrol/self/lib.php | 4 ++ enrol/self/tests/externallib_test.php | 96 +++++++++++++++++++++++++ enrol/self/version.php | 2 +- enrol/tests/externallib_test.php | 62 ++++++++++++++++ lib/db/services.php | 8 +++ 8 files changed, 363 insertions(+), 1 deletion(-) create mode 100644 enrol/self/db/services.php create mode 100644 enrol/self/externallib.php create mode 100644 enrol/self/tests/externallib_test.php diff --git a/enrol/externallib.php b/enrol/externallib.php index 582828e6298..ddfb976b384 100644 --- a/enrol/externallib.php +++ b/enrol/externallib.php @@ -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 index 00000000000..dd50355b61c --- /dev/null +++ b/enrol/self/db/services.php @@ -0,0 +1,34 @@ +. + +/** + * Self enrol plugin external functions and service definitions. + * + * @package enrol_self + * @copyright 2013 Rajesh Taneja + * @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 index 00000000000..4451087e439 --- /dev/null +++ b/enrol/self/externallib.php @@ -0,0 +1,100 @@ +. + +/** + * Self enrol plugin external functions + * + * @package enrol_self + * @copyright 2013 Rajesh Taneja + * @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 + * @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), + ) + ); + } +} diff --git a/enrol/self/lib.php b/enrol/self/lib.php index 86a88998021..9b0fa481fcc 100644 --- a/enrol/self/lib.php +++ b/enrol/self/lib.php @@ -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 index 00000000000..343af57fd67 --- /dev/null +++ b/enrol/self/tests/externallib_test.php @@ -0,0 +1,96 @@ +. + +/** + * Self enrol external PHPunit tests + * + * @package enrol_self + * @copyright 2013 Rajesh Taneja + * @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']); + } +} diff --git a/enrol/self/version.php b/enrol/self/version.php index c0d980e6460..b186821b556 100644 --- a/enrol/self/version.php +++ b/enrol/self/version.php @@ -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; diff --git a/enrol/tests/externallib_test.php b/enrol/tests/externallib_test.php index c93ebcb17ef..b4e8c50cbd4 100644 --- a/enrol/tests/externallib_test.php +++ b/enrol/tests/externallib_test.php @@ -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']); + } } diff --git a/lib/db/services.php b/lib/db/services.php index ec515a8bbfe..6b377d7bb07 100644 --- a/lib/db/services.php +++ b/lib/db/services.php @@ -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(