MDL-66269 enrol: A new webservice to search course participants
[moodle.git] / enrol / externallib.php
index 9bf1e5d..89137f1 100644 (file)
@@ -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
      *