From 0f308fcda71202a868f18aa906e90cebacff2fba Mon Sep 17 00:00:00 2001 From: Shamim Rezaie Date: Mon, 19 Aug 2019 06:50:49 +1000 Subject: [PATCH] MDL-66269 enrol: A new webservice to search course participants Part of MDL-66075. --- enrol/externallib.php | 92 +++++++++++++++++++++++++++++++++++++++++++ lib/db/services.php | 9 +++++ 2 files changed, 101 insertions(+) diff --git a/enrol/externallib.php b/enrol/externallib.php index 9bf1e5dd159..89137f1ba79 100644 --- a/enrol/externallib.php +++ b/enrol/externallib.php @@ -584,6 +584,98 @@ class core_enrol_external extends external_api { return new external_multiple_structure(core_user_external::user_description()); } + /** + * Returns description of method parameters + * + * @return external_function_parameters + */ + public static function search_users_parameters(): external_function_parameters { + return new external_function_parameters( + [ + 'courseid' => new external_value(PARAM_INT, 'course id'), + 'search' => new external_value(PARAM_RAW, 'query'), + 'searchanywhere' => new external_value(PARAM_BOOL, 'find a match anywhere, or only at the beginning'), + 'page' => new external_value(PARAM_INT, 'Page number'), + 'perpage' => new external_value(PARAM_INT, 'Number per page'), + ] + ); + } + + /** + * Search course participants. + * + * @param int $courseid Course id + * @param string $search The query + * @param bool $searchanywhere Match anywhere in the string + * @param int $page Page number + * @param int $perpage Max per page + * @return array An array of users + * @throws moodle_exception + */ + public static function search_users(int $courseid, string $search, bool $searchanywhere, int $page, int $perpage): array { + global $PAGE, $DB, $CFG; + + require_once($CFG->dirroot.'/enrol/locallib.php'); + require_once($CFG->dirroot.'/user/lib.php'); + + $params = self::validate_parameters( + self::search_users_parameters(), + [ + 'courseid' => $courseid, + 'search' => $search, + 'searchanywhere' => $searchanywhere, + 'page' => $page, + 'perpage' => $perpage + ] + ); + $context = context_course::instance($params['courseid']); + try { + self::validate_context($context); + } catch (Exception $e) { + $exceptionparam = new stdClass(); + $exceptionparam->message = $e->getMessage(); + $exceptionparam->courseid = $params['courseid']; + throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam); + } + course_require_view_participants($context); + + $course = $DB->get_record('course', ['id' => $params['courseid']]); + $manager = new course_enrolment_manager($PAGE, $course); + + $users = $manager->search_users($params['search'], + $params['searchanywhere'], + $params['page'], + $params['perpage']); + + $results = []; + // Add also extra user fields. + $requiredfields = array_merge( + ['id', 'fullname', 'profileimageurl', 'profileimageurlsmall'], + get_extra_user_fields($context) + ); + foreach ($users['users'] as $user) { + // Note: We pass the course here to validate that the current user can at least view user details in this course. + // The user we are looking at is not in this course yet though - but we only fetch the minimal set of + // user records, and the user has been validated to have course:enrolreview in this course. Otherwise + // there is no way to find users who aren't in the course in order to enrol them. + if ($userdetails = user_get_user_details($user, $course, $requiredfields)) { + $results[] = $userdetails; + } + } + return $results; + } + + /** + * Returns description of method result value + * + * @return external_multiple_structure + */ + public static function search_users_returns(): external_multiple_structure { + global $CFG; + require_once($CFG->dirroot . '/user/externallib.php'); + return new external_multiple_structure(core_user_external::user_description()); + } + /** * Returns description of method parameters * diff --git a/lib/db/services.php b/lib/db/services.php index 62b74b1db54..fd519a10501 100644 --- a/lib/db/services.php +++ b/lib/db/services.php @@ -634,6 +634,15 @@ $functions = array( 'type' => 'read', 'capabilities' => 'moodle/course:enrolreview' ), + 'core_enrol_search_users' => [ + 'classname' => 'core_enrol_external', + 'methodname' => 'search_users', + 'classpath' => 'enrol/externallib.php', + 'description' => 'Search within the list of course participants', + 'ajax' => true, + 'type' => 'read', + 'capabilities' => 'moodle/course:viewparticipants', + ], 'core_enrol_get_users_courses' => array( 'classname' => 'core_enrol_external', 'methodname' => 'get_users_courses', -- 2.43.0