search/classes/external.php

   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
  25 namespace core_search;
  26
  27 use core_external\external_function_parameters;
  28 use core_external\external_multiple_structure;
  29 use core_external\external_single_structure;
  30 use core_external\external_value;
  31 use core_user\external\user_summary_exporter;
  32
  33 /**
  34  * Handles external (web service) function calls related to search.
  35  *
  36  * @package core_search
  37  * @copyright 2017 The Open University
  38  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  39  */
  40 class external extends \core_external\external_api {
  41     /**
  42      * Returns parameter types for get_relevant_users function.
  43      *
  44      * @return external_function_parameters Parameters
  45      */
  46     public static function get_relevant_users_parameters() {
  47         return new external_function_parameters([
  48             'query' => new external_value(
  49                 PARAM_RAW,
  50                 'Query string (full or partial user full name or other details)'
  51             ),
  52             'courseid' => new external_value(PARAM_INT, 'Course id (0 if none)'),
  53         ]);
  54     }
  55
  56     /**
  57      * Returns result type for get_relevant_users function.
  58      *
  59      * @return external_description Result type
  60      */
  61     public static function get_relevant_users_returns() {
  62         return new external_multiple_structure(
  63             new external_single_structure([
  64                 'id' => new external_value(PARAM_INT, 'User id'),
  65                 'fullname' => new external_value(PARAM_RAW, 'Full name as text'),
  66                 'profileimageurlsmall' => new external_value(PARAM_URL, 'URL to small profile image')
  67             ])
  68         );
  69     }
  70
  71     /**
  72      * Searches for users given a query, taking into account the current user's permissions and
  73      * possibly a course to check within.
  74      *
  75      * @param string $query Query text
  76      * @param int $courseid Course id or 0 if no restriction
  77      * @return array Defined return structure
  78      */
  79     public static function get_relevant_users($query, $courseid) {
  80         global $CFG, $PAGE;
  81
  82         // Validate parameter.
  83         [
  84             'query' => $query,
  85             'courseid' => $courseid,
  86         ] = self::validate_parameters(self::get_relevant_users_parameters(), [
  87             'query' => $query,
  88             'courseid' => $courseid,
  89         ]);
  90
  91         // Validate the context (search page is always system context).
  92         $systemcontext = \context_system::instance();
  93         self::validate_context($systemcontext);
  94
  95         // Get course object too.
  96         if ($courseid) {
  97             $coursecontext = \context_course::instance($courseid);
  98         } else {
  99             $coursecontext = null;
 100         }
 101
 102         // If not logged in, can't see anyone when forceloginforprofiles is on.
 103         if (!empty($CFG->forceloginforprofiles)) {
 104             if (!isloggedin() || isguestuser()) {
 105                 return [];
 106             }
 107         }
 108
 109         $users = \core_user::search($query, $coursecontext);
 110
 111         $result = [];
 112         foreach ($users as $user) {
 113             // Get a standard exported user object.
 114             $fulldetails = (new user_summary_exporter($user))->export($PAGE->get_renderer('core'));
 115
 116             // To avoid leaking private data to students, only include the specific information we
 117             // are going to display (and not the email, idnumber, etc).
 118             $result[] = (object)['id' => $fulldetails->id, 'fullname' => $fulldetails->fullname,
 119                     'profileimageurlsmall' => $fulldetails->profileimageurlsmall];
 120         }
 121         return $result;
 122     }
 123 }