diff --git a/lib/db/services.php b/lib/db/services.php index 419dac54238..aed15b9e875 100644 --- a/lib/db/services.php +++ b/lib/db/services.php @@ -1166,6 +1166,7 @@ $services = array( 'mod_chat_send_chat_message', 'mod_chat_get_chat_latest_messages', 'mod_chat_view_chat', + 'mod_chat_get_chats_by_courses', 'mod_book_view_book', 'mod_choice_get_choice_results', 'mod_choice_get_choice_options', diff --git a/lib/externallib.php b/lib/externallib.php index 035ba6346cf..fc87c50dcff 100644 --- a/lib/externallib.php +++ b/lib/externallib.php @@ -346,7 +346,7 @@ class external_api { * @param stdClass $context * @since Moodle 2.0 */ - protected static function validate_context($context) { + public static function validate_context($context) { global $CFG; if (empty($context)) { @@ -876,3 +876,46 @@ class external_settings { return $this->file; } } + +/** + * Utility functions for the external API. + * + * @package core_webservice + * @copyright 2015 Juan Leyva + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @since Moodle 3.0 + */ +class external_util { + + /** + * Validate a list of courses, returning the complete course objects for valid courses. + * + * @param array $courseids A list of course ids + * @return array An array of courses and the validation warnings + */ + public static function validate_courses($courseids) { + // Delete duplicates. + $courseids = array_unique($courseids); + $courses = array(); + $warnings = array(); + + foreach ($courseids as $cid) { + // Check the user can function in this context. + try { + $context = context_course::instance($cid); + external_api::validate_context($context); + $courses[$cid] = get_course($cid); + } catch (Exception $e) { + $warnings[] = array( + 'item' => 'course', + 'itemid' => $cid, + 'warningcode' => '1', + 'message' => 'No access rights in course context' + ); + } + } + + return array($courses, $warnings); + } + +} diff --git a/lib/upgrade.txt b/lib/upgrade.txt index 0030babf7ee..874ea3d8303 100644 --- a/lib/upgrade.txt +++ b/lib/upgrade.txt @@ -133,6 +133,7 @@ information provided here is intended especially for developers. * The actionmenu hideMenu() function now expects an EventFacade object to be passed to it, i.e. a call to M.core.actionmenu.instance.hideMenu() should be change to M.core.actionmenu.instance.hideMenu(e) * In the html_editors (tinyMCE, Atto), the manage files button can be hidden by changing the 'enable_filemanagement' option to false. +* external_api::validate_context now is public, it can be called from other classes. === 2.9.1 === diff --git a/mod/chat/classes/external.php b/mod/chat/classes/external.php index 26204d68a48..56d70c69cc4 100644 --- a/mod/chat/classes/external.php +++ b/mod/chat/classes/external.php @@ -493,4 +493,121 @@ class mod_chat_external extends external_api { ); } + + /** + * Describes the parameters for get_chats_by_courses. + * + * @return external_external_function_parameters + * @since Moodle 3.0 + */ + public static function get_chats_by_courses_parameters() { + return new external_function_parameters ( + array( + 'courseids' => new external_multiple_structure( + new external_value(PARAM_INT, 'course id'), 'Array of course ids', VALUE_DEFAULT, array() + ), + ) + ); + } + + /** + * Returns a list of chats in a provided list of courses, + * if no list is provided all chats that the user can view will be returned. + * + * @param array $courseids the course ids + * @return array of chats details + * @since Moodle 3.0 + */ + public static function get_chats_by_courses($courseids = array()) { + global $CFG; + + $returnedchats = array(); + $warnings = array(); + + $params = self::validate_parameters(self::get_chats_by_courses_parameters(), array('courseids' => $courseids)); + + if (empty($params['courseids'])) { + $params['courseids'] = array_keys(enrol_get_my_courses()); + } + + // Ensure there are courseids to loop through. + if (!empty($params['courseids'])) { + + list($courses, $warnings) = external_util::validate_courses($params['courseids']); + + // Get the chats in this course, this function checks users visibility permissions. + // We can avoid then additional validate_context calls. + $chats = get_all_instances_in_courses("chat", $courses); + foreach ($chats as $chat) { + $chatcontext = context_module::instance($chat->coursemodule); + // Entry to return. + $chatdetails = array(); + // First, we return information that any user can see in the web interface. + $chatdetails['id'] = $chat->id; + $chatdetails['coursemodule'] = $chat->coursemodule; + $chatdetails['course'] = $chat->course; + $chatdetails['name'] = $chat->name; + // Format intro. + list($chatdetails['intro'], $chatdetails['introformat']) = + external_format_text($chat->intro, $chat->introformat, $chatcontext->id, 'mod_chat', 'intro', null); + + if (has_capability('mod/chat:chat', $chatcontext)) { + $chatdetails['chatmethod'] = $CFG->chat_method; + $chatdetails['keepdays'] = $chat->keepdays; + $chatdetails['studentlogs'] = $chat->studentlogs; + $chatdetails['chattime'] = $chat->chattime; + $chatdetails['schedule'] = $chat->schedule; + } + + if (has_capability('moodle/course:manageactivities', $chatcontext)) { + $chatdetails['timemodified'] = $chat->timemodified; + $chatdetails['section'] = $chat->section; + $chatdetails['visible'] = $chat->visible; + $chatdetails['groupmode'] = $chat->groupmode; + $chatdetails['groupingid'] = $chat->groupingid; + } + $returnedchats[] = $chatdetails; + } + } + $result = array(); + $result['chats'] = $returnedchats; + $result['warnings'] = $warnings; + return $result; + } + + /** + * Describes the get_chats_by_courses return value. + * + * @return external_single_structure + * @since Moodle 3.0 + */ + public static function get_chats_by_courses_returns() { + return new external_single_structure( + array( + 'chats' => new external_multiple_structure( + new external_single_structure( + array( + 'id' => new external_value(PARAM_INT, 'Chat id'), + 'coursemodule' => new external_value(PARAM_INT, 'Course module id'), + 'course' => new external_value(PARAM_TEXT, 'Course id'), + 'name' => new external_value(PARAM_TEXT, 'Chat name'), + 'intro' => new external_value(PARAM_RAW, 'The Chat intro'), + 'introformat' => new external_format_value('intro'), + 'chatmethod' => new external_value(PARAM_ALPHA, 'chat method (sockets, daemon)', VALUE_OPTIONAL), + 'keepdays' => new external_value(PARAM_INT, 'keep days', VALUE_OPTIONAL), + 'studentlogs' => new external_value(PARAM_INT, 'student logs visible to everyone', VALUE_OPTIONAL), + 'chattime' => new external_value(PARAM_RAW, 'chat time', VALUE_OPTIONAL), + 'schedule' => new external_value(PARAM_INT, 'schedule type', VALUE_OPTIONAL), + 'timemodified' => new external_value(PARAM_RAW, 'time of last modification', VALUE_OPTIONAL), + 'section' => new external_value(PARAM_INT, 'course section id', VALUE_OPTIONAL), + 'visible' => new external_value(PARAM_BOOL, 'visible', VALUE_OPTIONAL), + 'groupmode' => new external_value(PARAM_INT, 'group mode', VALUE_OPTIONAL), + 'groupingid' => new external_value(PARAM_INT, 'group id', VALUE_OPTIONAL), + ), 'Chats' + ) + ), + 'warnings' => new external_warnings(), + ) + ); + } } diff --git a/mod/chat/db/services.php b/mod/chat/db/services.php index 750943fba92..2361aace2de 100644 --- a/mod/chat/db/services.php +++ b/mod/chat/db/services.php @@ -68,4 +68,12 @@ $functions = array( 'capabilities' => 'mod/chat:chat' ), + 'mod_chat_get_chats_by_courses' => array( + 'classname' => 'mod_chat_external', + 'methodname' => 'get_chats_by_courses', + 'description' => 'Returns a list of chat instances in a provided set of courses, + if no courses are provided then all the chat instances the user has access to will be returned.', + 'type' => 'read', + 'capabilities' => '' + ) ); diff --git a/mod/chat/tests/externallib_test.php b/mod/chat/tests/externallib_test.php index 5497b24a941..cbd335f99f3 100644 --- a/mod/chat/tests/externallib_test.php +++ b/mod/chat/tests/externallib_test.php @@ -217,6 +217,72 @@ class mod_chat_external_testcase extends externallib_advanced_testcase { } catch (moodle_exception $e) { $this->assertEquals('nopermissions', $e->errorcode); } + } + + /** + * Test get_chats_by_courses + */ + public function test_get_chats_by_courses() { + global $DB, $USER; + $this->resetAfterTest(true); + $this->setAdminUser(); + $course1 = self::getDataGenerator()->create_course(); + $chatoptions1 = array( + 'course' => $course1->id, + 'name' => 'First Chat' + ); + $chat1 = self::getDataGenerator()->create_module('chat', $chatoptions1); + $course2 = self::getDataGenerator()->create_course(); + $chatoptions2 = array( + 'course' => $course2->id, + 'name' => 'Second Chat' + ); + $chat2 = self::getDataGenerator()->create_module('chat', $chatoptions2); + $student1 = $this->getDataGenerator()->create_user(); + $studentrole = $DB->get_record('role', array('shortname' => 'student')); + + // Enroll Student1 in Course1. + self::getDataGenerator()->enrol_user($student1->id, $course1->id, $studentrole->id); + $this->setUser($student1); + + $chats = mod_chat_external::get_chats_by_courses(); + // We need to execute the return values cleaning process to simulate the web service server. + $chats = external_api::clean_returnvalue(mod_chat_external::get_chats_by_courses_returns(), $chats); + $this->assertCount(1, $chats['chats']); + $this->assertEquals('First Chat', $chats['chats'][0]['name']); + // We see 11 fields. + $this->assertCount(11, $chats['chats'][0]); + + // As Student you cannot see some chat properties like 'section'. + $this->assertFalse(isset($chats['chats'][0]['section'])); + + // Student1 is not enrolled in course2. The webservice will return a warning! + $chats = mod_chat_external::get_chats_by_courses(array($course2->id)); + // We need to execute the return values cleaning process to simulate the web service server. + $chats = external_api::clean_returnvalue(mod_chat_external::get_chats_by_courses_returns(), $chats); + $this->assertCount(0, $chats['chats']); + $this->assertEquals(1, $chats['warnings'][0]['warningcode']); + + // Now as admin. + $this->setAdminUser(); + // As Admin we can see this chat. + $chats = mod_chat_external::get_chats_by_courses(array($course2->id)); + // We need to execute the return values cleaning process to simulate the web service server. + $chats = external_api::clean_returnvalue(mod_chat_external::get_chats_by_courses_returns(), $chats); + + $this->assertCount(1, $chats['chats']); + $this->assertEquals('Second Chat', $chats['chats'][0]['name']); + // We see 16 fields. + $this->assertCount(16, $chats['chats'][0]); + // As an Admin you can see some chat properties like 'section'. + $this->assertEquals(0, $chats['chats'][0]['section']); + + // Enrol student in the second course. + self::getDataGenerator()->enrol_user($student1->id, $course2->id, $studentrole->id); + $this->setUser($student1); + $chats = mod_chat_external::get_chats_by_courses(); + $chats = external_api::clean_returnvalue(mod_chat_external::get_chats_by_courses_returns(), $chats); + $this->assertCount(2, $chats['chats']); } } diff --git a/version.php b/version.php index 3433b036d01..7abced91f4d 100644 --- a/version.php +++ b/version.php @@ -29,7 +29,7 @@ defined('MOODLE_INTERNAL') || die(); -$version = 2015090901.00; // YYYYMMDD = weekly release date of this DEV branch. +$version = 2015090902.00; // YYYYMMDD = weekly release date of this DEV branch. // RR = release increments - 00 in DEV branches. // .XX = incremental changes.