);
}
+ /**
+ * Update courses
+ *
+ * @return external_function_parameters
+ * @since Moodle 2.5
+ */
+ public static function update_courses_parameters() {
+ return new external_function_parameters(
+ array(
+ 'courses' => new external_multiple_structure(
+ new external_single_structure(
+ array(
+ 'id' => new external_value(PARAM_INT, 'ID of the course'),
+ 'fullname' => new external_value(PARAM_TEXT, 'full name', VALUE_OPTIONAL),
+ 'shortname' => new external_value(PARAM_TEXT, 'course short name', VALUE_OPTIONAL),
+ 'categoryid' => new external_value(PARAM_INT, 'category id', VALUE_OPTIONAL),
+ 'idnumber' => new external_value(PARAM_RAW, 'id number', VALUE_OPTIONAL),
+ 'summary' => new external_value(PARAM_RAW, 'summary', VALUE_OPTIONAL),
+ 'summaryformat' => new external_format_value('summary', VALUE_OPTIONAL),
+ 'format' => new external_value(PARAM_PLUGIN,
+ 'course format: weeks, topics, social, site,..', VALUE_OPTIONAL),
+ 'showgrades' => new external_value(PARAM_INT,
+ '1 if grades are shown, otherwise 0', VALUE_OPTIONAL),
+ 'newsitems' => new external_value(PARAM_INT,
+ 'number of recent items appearing on the course page', VALUE_OPTIONAL),
+ 'startdate' => new external_value(PARAM_INT,
+ 'timestamp when the course start', VALUE_OPTIONAL),
+ 'numsections' => new external_value(PARAM_INT,
+ '(deprecated, use courseformatoptions) number of weeks/topics', VALUE_OPTIONAL),
+ 'maxbytes' => new external_value(PARAM_INT,
+ 'largest size of file that can be uploaded into the course', VALUE_OPTIONAL),
+ 'showreports' => new external_value(PARAM_INT,
+ 'are activity report shown (yes = 1, no =0)', VALUE_OPTIONAL),
+ 'visible' => new external_value(PARAM_INT,
+ '1: available to student, 0:not available', VALUE_OPTIONAL),
+ 'hiddensections' => new external_value(PARAM_INT,
+ '(deprecated, use courseformatoptions) How the hidden sections in the course are
+ displayed to students', VALUE_OPTIONAL),
+ 'groupmode' => new external_value(PARAM_INT, 'no group, separate, visible', VALUE_OPTIONAL),
+ 'groupmodeforce' => new external_value(PARAM_INT, '1: yes, 0: no', VALUE_OPTIONAL),
+ 'defaultgroupingid' => new external_value(PARAM_INT, 'default grouping id', VALUE_OPTIONAL),
+ 'enablecompletion' => new external_value(PARAM_INT,
+ 'Enabled, control via completion and activity settings. Disabled,
+ not shown in activity settings.', VALUE_OPTIONAL),
+ 'completionstartonenrol' => new external_value(PARAM_INT,
+ '1: begin tracking a student\'s progress in course completion after
+ course enrolment. 0: does not', VALUE_OPTIONAL),
+ 'completionnotify' => new external_value(PARAM_INT, '1: yes 0: no', VALUE_OPTIONAL),
+ 'lang' => new external_value(PARAM_SAFEDIR, 'forced course language', VALUE_OPTIONAL),
+ 'forcetheme' => new external_value(PARAM_PLUGIN, 'name of the force theme', VALUE_OPTIONAL),
+ 'courseformatoptions' => new external_multiple_structure(
+ new external_single_structure(
+ array('name' => new external_value(PARAM_ALPHANUMEXT, 'course format option name'),
+ 'value' => new external_value(PARAM_RAW, 'course format option value')
+ )),
+ 'additional options for particular course format', VALUE_OPTIONAL),
+ )
+ ), 'courses to update'
+ )
+ )
+ );
+ }
+
+ /**
+ * Update courses
+ *
+ * @param array $courses
+ * @since Moodle 2.5
+ */
+ public static function update_courses($courses) {
+ global $CFG, $DB;
+ require_once($CFG->dirroot . "/course/lib.php");
+ $warnings = array();
+
+ $params = self::validate_parameters(self::update_courses_parameters(),
+ array('courses' => $courses));
+
+ $availablethemes = get_plugin_list('theme');
+ $availablelangs = get_string_manager()->get_list_of_translations();
+
+ foreach ($params['courses'] as $course) {
+ // Catch any exception while updating course and return as warning to user.
+ try {
+ // Ensure the current user is allowed to run this function.
+ $context = context_course::instance($course['id'], MUST_EXIST);
+ self::validate_context($context);
+
+ $oldcourse = course_get_format($course['id'])->get_course();
+
+ require_capability('moodle/course:update', $context);
+
+ // Check if user can change category.
+ if (array_key_exists('categoryid', $course) && ($oldcourse->category != $course['categoryid'])) {
+ require_capability('moodle/course:changecategory', $context);
+ $course['category'] = $course['categoryid'];
+ }
+
+ // Check if the user can change fullname.
+ if (array_key_exists('fullname', $course) && ($oldcourse->fullname != $course['fullname'])) {
+ require_capability('moodle/course:changefullname', $context);
+ }
+
+ // Check if the shortname already exist and user have capability.
+ if (array_key_exists('shortname', $course) && ($oldcourse->shortname != $course['shortname'])) {
+ require_capability('moodle/course:changeshortname', $context);
+ if ($DB->record_exists('course', array('shortname' => $course['shortname']))) {
+ throw new moodle_exception('shortnametaken');
+ }
+ }
+
+ // Check if the id number already exist and user have capability.
+ if (array_key_exists('idnumber', $course) && ($oldcourse->idnumber != $course['idnumber'])) {
+ require_capability('moodle/course:changeidnumber', $context);
+ if ($DB->record_exists('course', array('idnumber' => $course['idnumber']))) {
+ throw new moodle_exception('idnumbertaken');
+ }
+ }
+
+ // Check if user can change summary.
+ if (array_key_exists('summary', $course) && ($oldcourse->summary != $course['summary'])) {
+ require_capability('moodle/course:changesummary', $context);
+ }
+
+ // Summary format.
+ if (array_key_exists('summaryformat', $course) && ($oldcourse->summaryformat != $course['summaryformat'])) {
+ require_capability('moodle/course:changesummary', $context);
+ $course['summaryformat'] = external_validate_format($course['summaryformat']);
+ }
+
+ // Check if user can change visibility.
+ if (array_key_exists('visible', $course) && ($oldcourse->visible != $course['visible'])) {
+ require_capability('moodle/course:visibility', $context);
+ }
+
+ // Make sure lang is valid.
+ if (array_key_exists('lang', $course) && empty($availablelangs[$course['lang']])) {
+ throw new moodle_exception('errorinvalidparam', 'webservice', '', 'lang');
+ }
+
+ // Make sure theme is valid.
+ if (array_key_exists('forcetheme', $course)) {
+ if (!empty($CFG->allowcoursethemes)) {
+ if (empty($availablethemes[$course['forcetheme']])) {
+ throw new moodle_exception('errorinvalidparam', 'webservice', '', 'forcetheme');
+ } else {
+ $course['theme'] = $course['forcetheme'];
+ }
+ }
+ }
+
+ // Make sure completion is enabled before setting it.
+ if ((array_key_exists('enabledcompletion', $course) ||
+ array_key_exists('completionstartonenrol', $course)) &&
+ !completion_info::is_enabled_for_site()) {
+ $course['enabledcompletion'] = 0;
+ $course['completionstartonenrol'] = 0;
+ }
+
+ // Make sure maxbytes are less then CFG->maxbytes.
+ if (array_key_exists('maxbytes', $course)) {
+ $course['maxbytes'] = get_max_upload_file_size($CFG->maxbytes, $course['maxbytes']);
+ }
+
+ if (!empty($course['courseformatoptions'])) {
+ foreach ($course['courseformatoptions'] as $option) {
+ if (isset($option['name']) && isset($option['value'])) {
+ $course[$option['name']] = $option['value'];
+ }
+ }
+ }
+
+ // Update course if user has all required capabilities.
+ update_course((object) $course);
+ } catch (Exception $e) {
+ $warning = array();
+ $warning['item'] = 'course';
+ $warning['itemid'] = $course['id'];
+ if ($e instanceof moodle_exception) {
+ $warning['warningcode'] = $e->errorcode;
+ } else {
+ $warning['warningcode'] = $e->getCode();
+ }
+ $warning['message'] = $e->getMessage();
+ $warnings[] = $warning;
+ }
+ }
+
+ $result = array();
+ $result['warnings'] = $warnings;
+ return $result;
+ }
+
+ /**
+ * Returns description of method result value
+ *
+ * @return external_description
+ * @since Moodle 2.5
+ */
+ public static function update_courses_returns() {
+ return new external_single_structure(
+ array(
+ 'warnings' => new external_warnings()
+ )
+ );
+ }
+
/**
* Returns description of method parameters
*
// Check that the course has been duplicated.
$this->assertEquals($newcourse['shortname'], $duplicate['shortname']);
}
+
+ /**
+ * Test update_courses
+ */
+ public function test_update_courses() {
+ global $DB, $CFG, $USER;
+
+ $this->resetAfterTest(true);
+
+ // Set the required capabilities by the external function.
+ $contextid = context_system::instance()->id;
+ $roleid = $this->assignUserCapability('moodle/course:update', $contextid);
+ $this->assignUserCapability('moodle/course:changecategory', $contextid, $roleid);
+ $this->assignUserCapability('moodle/course:changefullname', $contextid, $roleid);
+ $this->assignUserCapability('moodle/course:changeshortname', $contextid, $roleid);
+ $this->assignUserCapability('moodle/course:changeidnumber', $contextid, $roleid);
+ $this->assignUserCapability('moodle/course:changesummary', $contextid, $roleid);
+ $this->assignUserCapability('moodle/course:visibility', $contextid, $roleid);
+ $this->assignUserCapability('moodle/course:viewhiddencourses', $contextid, $roleid);
+
+ // Create category and course.
+ $category1 = self::getDataGenerator()->create_category();
+ $category2 = self::getDataGenerator()->create_category();
+ $originalcourse1 = self::getDataGenerator()->create_course();
+ self::getDataGenerator()->enrol_user($USER->id, $originalcourse1->id, $roleid);
+ $originalcourse2 = self::getDataGenerator()->create_course();
+ self::getDataGenerator()->enrol_user($USER->id, $originalcourse2->id, $roleid);
+
+ // Course values to be updated.
+ $course1['id'] = $originalcourse1->id;
+ $course1['fullname'] = 'Updated test course 1';
+ $course1['shortname'] = 'Udestedtestcourse1';
+ $course1['categoryid'] = $category1->id;
+ $course2['id'] = $originalcourse2->id;
+ $course2['fullname'] = 'Updated test course 2';
+ $course2['shortname'] = 'Updestedtestcourse2';
+ $course2['categoryid'] = $category2->id;
+ $course2['idnumber'] = 'Updatedidnumber2';
+ $course2['summary'] = 'Updaated description for course 2';
+ $course2['summaryformat'] = FORMAT_HTML;
+ $course2['format'] = 'topics';
+ $course2['showgrades'] = 1;
+ $course2['newsitems'] = 3;
+ $course2['startdate'] = 1420092000; // 01/01/2015.
+ $course2['numsections'] = 4;
+ $course2['maxbytes'] = 100000;
+ $course2['showreports'] = 1;
+ $course2['visible'] = 0;
+ $course2['hiddensections'] = 0;
+ $course2['groupmode'] = 0;
+ $course2['groupmodeforce'] = 0;
+ $course2['defaultgroupingid'] = 0;
+ $course2['enablecompletion'] = 1;
+ $course2['lang'] = 'en';
+ $course2['forcetheme'] = 'base';
+ $courses = array($course1, $course2);
+
+ $updatedcoursewarnings = core_course_external::update_courses($courses);
+
+ // Check that right number of courses were created.
+ $this->assertEquals(0, count($updatedcoursewarnings['warnings']));
+
+ // Check that the courses were correctly created.
+ foreach ($courses as $course) {
+ $courseinfo = course_get_format($course['id'])->get_course();
+ if ($course['id'] == $course2['id']) {
+ $this->assertEquals($course2['fullname'], $courseinfo->fullname);
+ $this->assertEquals($course2['shortname'], $courseinfo->shortname);
+ $this->assertEquals($course2['categoryid'], $courseinfo->category);
+ $this->assertEquals($course2['idnumber'], $courseinfo->idnumber);
+ $this->assertEquals($course2['summary'], $courseinfo->summary);
+ $this->assertEquals($course2['summaryformat'], $courseinfo->summaryformat);
+ $this->assertEquals($course2['format'], $courseinfo->format);
+ $this->assertEquals($course2['showgrades'], $courseinfo->showgrades);
+ $this->assertEquals($course2['newsitems'], $courseinfo->newsitems);
+ $this->assertEquals($course2['startdate'], $courseinfo->startdate);
+ $this->assertEquals($course2['numsections'], $courseinfo->numsections);
+ $this->assertEquals($course2['maxbytes'], $courseinfo->maxbytes);
+ $this->assertEquals($course2['showreports'], $courseinfo->showreports);
+ $this->assertEquals($course2['visible'], $courseinfo->visible);
+ $this->assertEquals($course2['hiddensections'], $courseinfo->hiddensections);
+ $this->assertEquals($course2['groupmode'], $courseinfo->groupmode);
+ $this->assertEquals($course2['groupmodeforce'], $courseinfo->groupmodeforce);
+ $this->assertEquals($course2['defaultgroupingid'], $courseinfo->defaultgroupingid);
+ $this->assertEquals($course2['lang'], $courseinfo->lang);
+
+ if (!empty($CFG->allowcoursethemes)) {
+ $this->assertEquals($course2['forcetheme'], $courseinfo->theme);
+ }
+
+ if (completion_info::is_enabled_for_site()) {
+ $this->assertEquals($course2['enabledcompletion'], $courseinfo->enablecompletion);
+ $this->assertEquals($course2['completionstartonenrol'], $courseinfo->completionstartonenrol);
+ }
+ } else if ($course['id'] == $course1['id']) {
+ $this->assertEquals($course1['fullname'], $courseinfo->fullname);
+ $this->assertEquals($course1['shortname'], $courseinfo->shortname);
+ $this->assertEquals($course1['categoryid'], $courseinfo->category);
+ $this->assertEquals(FORMAT_MOODLE, $courseinfo->summaryformat);
+ $this->assertEquals('topics', $courseinfo->format);
+ $this->assertEquals(5, $courseinfo->numsections);
+ $this->assertEquals(0, $courseinfo->newsitems);
+ $this->assertEquals(FORMAT_MOODLE, $courseinfo->summaryformat);
+ } else {
+ throw moodle_exception('Unexpected shortname');
+ }
+ }
+
+ $courses = array($course1);
+ // Try update course without update capability.
+ $user = self::getDataGenerator()->create_user();
+ $this->setUser($user);
+ $this->unassignUserCapability('moodle/course:update', $contextid, $roleid);
+ self::getDataGenerator()->enrol_user($user->id, $course1['id'], $roleid);
+ $updatedcoursewarnings = core_course_external::update_courses($courses);
+ $this->assertEquals(1, count($updatedcoursewarnings['warnings']));
+
+ // Try update course category without capability.
+ $this->assignUserCapability('moodle/course:update', $contextid, $roleid);
+ $this->unassignUserCapability('moodle/course:changecategory', $contextid, $roleid);
+ $user = self::getDataGenerator()->create_user();
+ $this->setUser($user);
+ self::getDataGenerator()->enrol_user($user->id, $course1['id'], $roleid);
+ $course1['categoryid'] = $category2->id;
+ $courses = array($course1);
+ $updatedcoursewarnings = core_course_external::update_courses($courses);
+ $this->assertEquals(1, count($updatedcoursewarnings['warnings']));
+
+ // Try update course fullname without capability.
+ $this->assignUserCapability('moodle/course:changecategory', $contextid, $roleid);
+ $this->unassignUserCapability('moodle/course:changefullname', $contextid, $roleid);
+ $user = self::getDataGenerator()->create_user();
+ $this->setUser($user);
+ self::getDataGenerator()->enrol_user($user->id, $course1['id'], $roleid);
+ $updatedcoursewarnings = core_course_external::update_courses($courses);
+ $this->assertEquals(0, count($updatedcoursewarnings['warnings']));
+ $course1['fullname'] = 'Testing fullname without permission';
+ $courses = array($course1);
+ $updatedcoursewarnings = core_course_external::update_courses($courses);
+ $this->assertEquals(1, count($updatedcoursewarnings['warnings']));
+
+ // Try update course shortname without capability.
+ $this->assignUserCapability('moodle/course:changefullname', $contextid, $roleid);
+ $this->unassignUserCapability('moodle/course:changeshortname', $contextid, $roleid);
+ $user = self::getDataGenerator()->create_user();
+ $this->setUser($user);
+ self::getDataGenerator()->enrol_user($user->id, $course1['id'], $roleid);
+ $updatedcoursewarnings = core_course_external::update_courses($courses);
+ $this->assertEquals(0, count($updatedcoursewarnings['warnings']));
+ $course1['shortname'] = 'Testing shortname without permission';
+ $courses = array($course1);
+ $updatedcoursewarnings = core_course_external::update_courses($courses);
+ $this->assertEquals(1, count($updatedcoursewarnings['warnings']));
+
+ // Try update course idnumber without capability.
+ $this->assignUserCapability('moodle/course:changeshortname', $contextid, $roleid);
+ $this->unassignUserCapability('moodle/course:changeidnumber', $contextid, $roleid);
+ $user = self::getDataGenerator()->create_user();
+ $this->setUser($user);
+ self::getDataGenerator()->enrol_user($user->id, $course1['id'], $roleid);
+ $updatedcoursewarnings = core_course_external::update_courses($courses);
+ $this->assertEquals(0, count($updatedcoursewarnings['warnings']));
+ $course1['idnumber'] = 'NEWIDNUMBER';
+ $courses = array($course1);
+ $updatedcoursewarnings = core_course_external::update_courses($courses);
+ $this->assertEquals(1, count($updatedcoursewarnings['warnings']));
+
+ // Try update course summary without capability.
+ $this->assignUserCapability('moodle/course:changeidnumber', $contextid, $roleid);
+ $this->unassignUserCapability('moodle/course:changesummary', $contextid, $roleid);
+ $user = self::getDataGenerator()->create_user();
+ $this->setUser($user);
+ self::getDataGenerator()->enrol_user($user->id, $course1['id'], $roleid);
+ $updatedcoursewarnings = core_course_external::update_courses($courses);
+ $this->assertEquals(0, count($updatedcoursewarnings['warnings']));
+ $course1['summary'] = 'New summary';
+ $courses = array($course1);
+ $updatedcoursewarnings = core_course_external::update_courses($courses);
+ $this->assertEquals(1, count($updatedcoursewarnings['warnings']));
+
+ // Try update course with invalid summary format.
+ $this->assignUserCapability('moodle/course:changesummary', $contextid, $roleid);
+ $user = self::getDataGenerator()->create_user();
+ $this->setUser($user);
+ self::getDataGenerator()->enrol_user($user->id, $course1['id'], $roleid);
+ $updatedcoursewarnings = core_course_external::update_courses($courses);
+ $this->assertEquals(0, count($updatedcoursewarnings['warnings']));
+ $course1['summaryformat'] = 10;
+ $courses = array($course1);
+ $updatedcoursewarnings = core_course_external::update_courses($courses);
+ $this->assertEquals(1, count($updatedcoursewarnings['warnings']));
+
+ // Try update course visibility without capability.
+ $this->unassignUserCapability('moodle/course:visibility', $contextid, $roleid);
+ $user = self::getDataGenerator()->create_user();
+ $this->setUser($user);
+ self::getDataGenerator()->enrol_user($user->id, $course1['id'], $roleid);
+ $course1['summaryformat'] = FORMAT_MOODLE;
+ $courses = array($course1);
+ $updatedcoursewarnings = core_course_external::update_courses($courses);
+ $this->assertEquals(0, count($updatedcoursewarnings['warnings']));
+ $course1['visible'] = 0;
+ $courses = array($course1);
+ $updatedcoursewarnings = core_course_external::update_courses($courses);
+ $this->assertEquals(1, count($updatedcoursewarnings['warnings']));
+ }
}
