From 0f308fcda71202a868f18aa906e90cebacff2fba Mon Sep 17 00:00:00 2001
From: Shamim Rezaie <shamim@moodle.com>
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.17.1