[Summary view]

Differences Between: [Versions 401 and 402] [Versions 401 and 403]

   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  namespace core_grades\external;
  18  
  19  use external_api;
  20  use external_function_parameters;
  21  use external_value;
  22  use external_single_structure;
  23  use external_multiple_structure;
  24  use moodle_url;
  25  use core_user;
  26  
  27  defined('MOODLE_INTERNAL') || die;
  28  
  29  require_once($CFG->dirroot.'/grade/lib.php');
  30  
  31  /**
  32   * Get the enrolled users within and map some fields to the returned array of user objects.
  33   *
  34   * @package    core_grades
  35   * @copyright  2022 Mihail Geshoski <mihail@moodle.com>
  36   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  37   * @since      Moodle 4.1
  38   */
  39  class get_enrolled_users_for_search_widget extends external_api {
  40  
  41      /**
  42       * Returns description of method parameters.
  43       *
  44       * @return external_function_parameters
  45       */
  46      public static function execute_parameters(): external_function_parameters {
  47          return new external_function_parameters (
  48              [
  49                  'courseid' => new external_value(PARAM_INT, 'Course Id', VALUE_REQUIRED),
  50                  'actionbaseurl' => new external_value(PARAM_URL, 'The base URL for the user option', VALUE_REQUIRED),
  51                  'groupid' => new external_value(PARAM_INT, 'Group Id', VALUE_DEFAULT, 0)
  52              ]
  53          );
  54      }
  55  
  56      /**
  57       * Given a course ID find the enrolled users within and map some fields to the returned array of user objects.
  58       *
  59       * @param int $courseid
  60       * @param string $actionbaseurl The base URL for the user option.
  61       * @param int|null $groupid
  62       * @return array Users and warnings to pass back to the calling widget.
  63       * @throws coding_exception
  64       * @throws invalid_parameter_exception
  65       * @throws moodle_exception
  66       * @throws restricted_context_exception
  67       */
  68      public static function execute(int $courseid, string $actionbaseurl, ?int $groupid = 0): array {
  69          global $DB, $PAGE;
  70  
  71          $params = self::validate_parameters(
  72              self::execute_parameters(),
  73              [
  74                  'courseid' => $courseid,
  75                  'actionbaseurl' => $actionbaseurl,
  76                  'groupid' => $groupid
  77              ]
  78          );
  79  
  80          $warnings = [];
  81          $coursecontext = \context_course::instance($params['courseid']);
  82          parent::validate_context($coursecontext);
  83  
  84          require_capability('moodle/course:viewparticipants', $coursecontext);
  85  
  86          $course = $DB->get_record('course', ['id' => $params['courseid']]);
  87          // Create a graded_users_iterator because it will properly check the groups etc.
  88          $defaultgradeshowactiveenrol = !empty($CFG->grade_report_showonlyactiveenrol);
  89          $showonlyactiveenrol = get_user_preferences('grade_report_showonlyactiveenrol', $defaultgradeshowactiveenrol);
  90          $showonlyactiveenrol = $showonlyactiveenrol || !has_capability('moodle/course:viewsuspendedusers', $coursecontext);
  91  
  92          $gui = new \graded_users_iterator($course, null, $params['groupid']);
  93          $gui->require_active_enrolment($showonlyactiveenrol);
  94          $gui->init();
  95  
  96          $users = [];
  97  
  98          while ($userdata = $gui->next_user()) {
  99              $guiuser = $userdata->user;
 100              $user = new \stdClass();
 101              $user->fullname = fullname($guiuser);
 102              $user->id = $guiuser->id;
 103              $user->url = (new moodle_url($actionbaseurl, ['id' => $courseid, 'userid' => $guiuser->id]))->out(false);
 104              $userpicture = new \user_picture($guiuser);
 105              $userpicture->size = 1;
 106              $user->profileimage = $userpicture->get_url($PAGE)->out(false);
 107              $user->email = $guiuser->email;
 108              $user->active = false; // @TODO MDL-76246
 109  
 110              $users[] = $user;
 111          }
 112          $gui->close();
 113  
 114          return [
 115              'users' => $users,
 116              'warnings' => $warnings,
 117          ];
 118      }
 119  
 120      /**
 121       * Returns description of method result value.
 122       *
 123       * @return external_single_structure
 124       */
 125      public static function execute_returns(): external_single_structure {
 126          return new external_single_structure([
 127              'users' => new external_multiple_structure(self::user_description()),
 128              'warnings' => new \external_warnings(),
 129          ]);
 130      }
 131  
 132      /**
 133       * Create user return value description.
 134       *
 135       * @return \external_description
 136       */
 137      public static function user_description(): \external_description {
 138          $userfields = [
 139              'id'    => new external_value(core_user::get_property_type('id'), 'ID of the user'),
 140              'profileimage' => new external_value(
 141                  PARAM_URL,
 142                  'The location of the users larger image',
 143                  VALUE_OPTIONAL
 144              ),
 145              'url' => new external_value(
 146                  PARAM_URL,
 147                  'The link to the user report',
 148                  VALUE_OPTIONAL
 149              ),
 150              'fullname' => new external_value(PARAM_TEXT, 'The full name of the user', VALUE_OPTIONAL),
 151              'email' => new external_value(
 152                  core_user::get_property_type('email'),
 153                  'An email address - allow email as root@localhost',
 154                  VALUE_OPTIONAL),
 155              'active' => new external_value(PARAM_BOOL, 'Are we currently on this item?', VALUE_REQUIRED)
 156          ];
 157          return new external_single_structure($userfields);
 158      }
 159  }