1<?php
2// This file is part of Moodle - http://moodle.org/
3//
4// Moodle is free software: you can redistribute it and/or modify
5// it under the terms of the GNU General Public License as published by
6// the Free Software Foundation, either version 3 of the License, or
7// (at your option) any later version.
8//
9// Moodle is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12// GNU General Public License for more details.
13//
14// You should have received a copy of the GNU General Public License
15// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
16
17/**
18 * Handles external (web service) function calls related to search.
19 *
20 * @package core_search
21 * @copyright 2017 The Open University
22 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
23 */
24
25namespace core_search;
26
27use core_user\external\user_summary_exporter;
28use \external_value;
29use \external_single_structure;
30use \external_multiple_structure;
31
32defined('MOODLE_INTERNAL') || die();
33
34global $CFG;
35require_once($CFG->libdir . '/externallib.php');
36
37/**
38 * Handles external (web service) function calls related to search.
39 *
40 * @package core_search
41 * @copyright 2017 The Open University
42 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
43 */
44class external extends \external_api {
45    /**
46     * Returns parameter types for get_relevant_users function.
47     *
48     * @return \external_function_parameters Parameters
49     */
50    public static function get_relevant_users_parameters() {
51        return new \external_function_parameters([
52                'query' => new external_value(PARAM_RAW,
53                    'Query string (full or partial user full name or other details)'),
54                'courseid' => new external_value(PARAM_INT, 'Course id (0 if none)'),
55                ]);
56    }
57
58    /**
59     * Returns result type for get_relevant_users function.
60     *
61     * @return \external_description Result type
62     */
63    public static function get_relevant_users_returns() {
64        return new external_multiple_structure(
65                new external_single_structure([
66                    'id' => new external_value(PARAM_INT, 'User id'),
67                    'fullname' => new external_value(PARAM_RAW, 'Full name as text'),
68                    'profileimageurlsmall' => new external_value(PARAM_URL, 'URL to small profile image')
69                ]));
70    }
71
72    /**
73     * Searches for users given a query, taking into account the current user's permissions and
74     * possibly a course to check within.
75     *
76     * @param string $query Query text
77     * @param int $courseid Course id or 0 if no restriction
78     * @return array Defined return structure
79     */
80    public static function get_relevant_users($query, $courseid) {
81        global $CFG, $PAGE;
82
83        // Validate parameter.
84        [
85            'query' => $query,
86            'courseid' => $courseid,
87        ] = self::validate_parameters(self::get_relevant_users_parameters(), [
88            'query' => $query,
89            'courseid' => $courseid,
90        ]);
91
92        // Validate the context (search page is always system context).
93        $systemcontext = \context_system::instance();
94        self::validate_context($systemcontext);
95
96        // Get course object too.
97        if ($courseid) {
98            $coursecontext = \context_course::instance($courseid);
99        } else {
100            $coursecontext = null;
101        }
102
103        // If not logged in, can't see anyone when forceloginforprofiles is on.
104        if (!empty($CFG->forceloginforprofiles)) {
105            if (!isloggedin() || isguestuser()) {
106                return [];
107            }
108        }
109
110        $users = \core_user::search($query, $coursecontext);
111
112        $result = [];
113        foreach ($users as $user) {
114            // Get a standard exported user object.
115            $fulldetails = (new user_summary_exporter($user))->export($PAGE->get_renderer('core'));
116
117            // To avoid leaking private data to students, only include the specific information we
118            // are going to display (and not the email, idnumber, etc).
119            $result[] = (object)['id' => $fulldetails->id, 'fullname' => $fulldetails->fullname,
120                    'profileimageurlsmall' => $fulldetails->profileimageurlsmall];
121        }
122        return $result;
123    }
124}
125